diff --git a/.release-please-manifest.json b/.release-please-manifest.json index b44b287..4dedeae 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "2.4.0" + ".": "2.5.0" } \ No newline at end of file diff --git a/.stats.yml b/.stats.yml index 7cfdbba..b9d1d30 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1,4 +1,4 @@ configured_endpoints: 30 -openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/context-dev/context.dev-fb56935a194e69348fecd985f7cf8b249795b46af2fb32f6c5c8ef648cf10c15.yml -openapi_spec_hash: 7260a560474283b7ad6ac5d426058ac9 +openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/context-dev/context.dev-d49b84cf1125618f171698ff1ee4ff9a8d04151619cb4a56d650103869834465.yml +openapi_spec_hash: 49b7a6f59dcdff1e2bf88feb6474a562 config_hash: daabb160675d86b354711da1e77e5129 diff --git a/CHANGELOG.md b/CHANGELOG.md index e0a0fd1..8a90494 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,14 @@ # Changelog +## 2.5.0 (2026-07-14) + +Full Changelog: [v2.4.0...v2.5.0](https://github.com/context-dot-dev/context-php-sdk/compare/v2.4.0...v2.5.0) + +### Features + +* **api:** api update ([ea009c4](https://github.com/context-dot-dev/context-php-sdk/commit/ea009c4ebae36d4f2fbe2bf2bccce55f0148dfe8)) +* **api:** api update ([8e18458](https://github.com/context-dot-dev/context-php-sdk/commit/8e18458a35402f1b085547b472601a563c77ae5b)) + ## 2.4.0 (2026-07-12) Full Changelog: [v2.3.0...v2.4.0](https://github.com/context-dot-dev/context-php-sdk/compare/v2.3.0...v2.4.0) diff --git a/README.md b/README.md index 6ab8d0a..ca69c9f 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ The REST API documentation can be found on [docs.context.dev](https://docs.conte ``` -composer require "context-dev/context-dev-php 2.4.0" +composer require "context-dev/context-dev-php 2.5.0" ``` diff --git a/src/AI/AIExtractProductParams.php b/src/AI/AIExtractProductParams.php index 52baa9b..d0b275e 100644 --- a/src/AI/AIExtractProductParams.php +++ b/src/AI/AIExtractProductParams.php @@ -16,7 +16,10 @@ * @see ContextDev\Services\AIService::extractProduct() * * @phpstan-type AIExtractProductParamsShape = array{ - * url: string, maxAgeMs?: int|null, timeoutMs?: int|null + * url: string, + * maxAgeMs?: int|null, + * tags?: list|null, + * timeoutMs?: int|null, * } */ final class AIExtractProductParams implements BaseModel @@ -37,6 +40,14 @@ final class AIExtractProductParams implements BaseModel #[Optional] public ?int $maxAgeMs; + /** + * Optional caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters. + * + * @var list|null $tags + */ + #[Optional(list: 'string')] + public ?array $tags; + /** * 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). */ @@ -66,10 +77,13 @@ public function __construct() * Construct an instance from the required parameters. * * You must use named parameters to construct any parameters with a default value. + * + * @param list|null $tags */ public static function with( string $url, ?int $maxAgeMs = null, + ?array $tags = null, ?int $timeoutMs = null ): self { $self = new self; @@ -77,6 +91,7 @@ public static function with( $self['url'] = $url; null !== $maxAgeMs && $self['maxAgeMs'] = $maxAgeMs; + null !== $tags && $self['tags'] = $tags; null !== $timeoutMs && $self['timeoutMs'] = $timeoutMs; return $self; @@ -104,6 +119,19 @@ public function withMaxAgeMs(int $maxAgeMs): self return $self; } + /** + * Optional caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters. + * + * @param list $tags + */ + public function withTags(array $tags): self + { + $self = clone $this; + $self['tags'] = $tags; + + return $self; + } + /** * 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). */ diff --git a/src/AI/AIExtractProductsParams.php b/src/AI/AIExtractProductsParams.php index 06f62a8..d5b264f 100644 --- a/src/AI/AIExtractProductsParams.php +++ b/src/AI/AIExtractProductsParams.php @@ -19,6 +19,7 @@ * domain: string, * maxAgeMs?: int|null, * maxProducts?: int|null, + * tags?: list|null, * timeoutMs?: int|null, * directURL: string, * } @@ -47,6 +48,14 @@ final class AIExtractProductsParams implements BaseModel #[Optional] public ?int $maxProducts; + /** + * Optional caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters. + * + * @var list|null $tags + */ + #[Optional(list: 'string')] + public ?array $tags; + /** * 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). */ @@ -82,12 +91,15 @@ public function __construct() * Construct an instance from the required parameters. * * You must use named parameters to construct any parameters with a default value. + * + * @param list|null $tags */ public static function with( string $domain, string $directURL, ?int $maxAgeMs = null, ?int $maxProducts = null, + ?array $tags = null, ?int $timeoutMs = null, ): self { $self = new self; @@ -97,6 +109,7 @@ public static function with( null !== $maxAgeMs && $self['maxAgeMs'] = $maxAgeMs; null !== $maxProducts && $self['maxProducts'] = $maxProducts; + null !== $tags && $self['tags'] = $tags; null !== $timeoutMs && $self['timeoutMs'] = $timeoutMs; return $self; @@ -135,6 +148,19 @@ public function withMaxProducts(int $maxProducts): self return $self; } + /** + * Optional caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters. + * + * @param list $tags + */ + public function withTags(array $tags): self + { + $self = clone $this; + $self['tags'] = $tags; + + return $self; + } + /** * 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). */ diff --git a/src/Brand/BrandGetResponse/Brand.php b/src/Brand/BrandGetResponse/Brand.php index c4e52be..23527d6 100644 --- a/src/Brand/BrandGetResponse/Brand.php +++ b/src/Brand/BrandGetResponse/Brand.php @@ -126,7 +126,7 @@ final class Brand implements BaseModel public ?string $phone; /** - * The primary language of the brand's website content. Detected from the HTML lang tag, page content analysis, or social media descriptions. + * Language to force for the retrieved brand data. * * @var value-of|null $primaryLanguage */ @@ -353,7 +353,7 @@ public function withPhone(string $phone): self } /** - * The primary language of the brand's website content. Detected from the HTML lang tag, page content analysis, or social media descriptions. + * Language to force for the retrieved brand data. * * @param PrimaryLanguage|value-of|null $primaryLanguage */ diff --git a/src/Brand/BrandGetResponse/Brand/Industries/Eic/Subindustry.php b/src/Brand/BrandGetResponse/Brand/Industries/Eic/Subindustry.php index c9fe4c5..b728b5d 100644 --- a/src/Brand/BrandGetResponse/Brand/Industries/Eic/Subindustry.php +++ b/src/Brand/BrandGetResponse/Brand/Industries/Eic/Subindustry.php @@ -109,8 +109,6 @@ enum Subindustry: string case CREATOR_ECONOMY_INFLUENCER_PLATFORMS = 'Creator Economy & Influencer Platforms'; - case ADVERTISING_ADTECH_MEDIA_BUYING = 'Advertising, Adtech & Media Buying'; - case FILM_TV_PRODUCTION_STUDIOS = 'Film, TV & Production Studios'; case EVENTS_VENUES_LIVE_ENTERTAINMENT = 'Events, Venues & Live Entertainment'; @@ -231,6 +229,8 @@ enum Subindustry: string case NEWS_PUBLISHING_JOURNALISM = 'News Publishing & Journalism'; + case ADVERTISING_ADTECH_MEDIA_BUYING = 'Advertising, Adtech & Media Buying'; + case DIGITAL_MEDIA_CONTENT_PLATFORMS = 'Digital Media & Content Platforms'; case BROADCASTING_TV_RADIO = 'Broadcasting (TV & Radio)'; diff --git a/src/Brand/BrandGetResponse/Brand/PrimaryLanguage.php b/src/Brand/BrandGetResponse/Brand/PrimaryLanguage.php index d8696bc..d66bc00 100644 --- a/src/Brand/BrandGetResponse/Brand/PrimaryLanguage.php +++ b/src/Brand/BrandGetResponse/Brand/PrimaryLanguage.php @@ -5,7 +5,7 @@ namespace ContextDev\Brand\BrandGetResponse\Brand; /** - * The primary language of the brand's website content. Detected from the HTML lang tag, page content analysis, or social media descriptions. + * Language to force for the retrieved brand data. */ enum PrimaryLanguage: string { diff --git a/src/Brand/BrandRetrieveParams.php b/src/Brand/BrandRetrieveParams.php index 4d98ff9..47f3afe 100644 --- a/src/Brand/BrandRetrieveParams.php +++ b/src/Brand/BrandRetrieveParams.php @@ -17,12 +17,18 @@ * * @see ContextDev\Services\BrandService::retrieve() * + * @phpstan-import-type MccVariants from \ContextDev\Brand\BrandRetrieveParams\Mcc + * @phpstan-import-type PhoneVariants from \ContextDev\Brand\BrandRetrieveParams\Phone + * @phpstan-import-type MccShape from \ContextDev\Brand\BrandRetrieveParams\Mcc + * @phpstan-import-type PhoneShape from \ContextDev\Brand\BrandRetrieveParams\Phone + * * @phpstan-type BrandRetrieveParamsShape = array{ * domain: string, * type: Type|value-of, * forceLanguage?: null|ForceLanguage|value-of, * maxAgeMs?: int|null, * maxSpeed?: bool|null, + * tags?: list|null, * timeoutMs?: int|null, * name: string, * countryGl?: string|null, @@ -33,8 +39,8 @@ * transactionInfo: string, * city?: string|null, * highConfidenceOnly?: bool|null, - * mcc?: int|null, - * phone?: float|null, + * mcc?: MccShape|null, + * phone?: PhoneShape|null, * } */ final class BrandRetrieveParams implements BaseModel @@ -58,7 +64,7 @@ final class BrandRetrieveParams implements BaseModel public string $type; /** @var value-of|null $forceLanguage */ - #[Optional('force_language', enum: ForceLanguage::class)] + #[Optional('force_language', enum: ForceLanguage::class, nullable: true)] public ?string $forceLanguage; /** @@ -73,6 +79,14 @@ final class BrandRetrieveParams implements BaseModel #[Optional] public ?bool $maxSpeed; + /** + * Optional caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters. + * + * @var list|null $tags + */ + #[Optional(list: 'string')] + public ?array $tags; + /** * 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). */ @@ -135,15 +149,19 @@ final class BrandRetrieveParams implements BaseModel /** * Optional Merchant Category Code (MCC) to help identify the business category or industry. + * + * @var MccVariants|null $mcc */ #[Optional] - public ?int $mcc; + public string|float|null $mcc; /** * Optional phone number from the transaction to help verify brand match. + * + * @var PhoneVariants|null $phone */ #[Optional] - public ?float $phone; + public string|float|null $phone; /** * `new BrandRetrieveParams()` is missing required properties by the API. @@ -186,6 +204,9 @@ public function __construct() * * @param Type|value-of $type * @param ForceLanguage|value-of|null $forceLanguage + * @param list|null $tags + * @param MccShape|null $mcc + * @param PhoneShape|null $phone */ public static function with( string $domain, @@ -198,13 +219,14 @@ public static function with( ForceLanguage|string|null $forceLanguage = null, ?int $maxAgeMs = null, ?bool $maxSpeed = null, + ?array $tags = null, ?int $timeoutMs = null, ?string $countryGl = null, ?string $tickerExchange = null, ?string $city = null, ?bool $highConfidenceOnly = null, - ?int $mcc = null, - ?float $phone = null, + string|float|null $mcc = null, + string|float|null $phone = null, ): self { $self = new self; @@ -219,6 +241,7 @@ public static function with( null !== $forceLanguage && $self['forceLanguage'] = $forceLanguage; null !== $maxAgeMs && $self['maxAgeMs'] = $maxAgeMs; null !== $maxSpeed && $self['maxSpeed'] = $maxSpeed; + null !== $tags && $self['tags'] = $tags; null !== $timeoutMs && $self['timeoutMs'] = $timeoutMs; null !== $countryGl && $self['countryGl'] = $countryGl; null !== $tickerExchange && $self['tickerExchange'] = $tickerExchange; @@ -255,10 +278,11 @@ public function withType(Type|string $type): self } /** - * @param ForceLanguage|value-of $forceLanguage + * @param ForceLanguage|value-of|null $forceLanguage */ - public function withForceLanguage(ForceLanguage|string $forceLanguage): self - { + public function withForceLanguage( + ForceLanguage|string|null $forceLanguage + ): self { $self = clone $this; $self['forceLanguage'] = $forceLanguage; @@ -287,6 +311,19 @@ public function withMaxSpeed(bool $maxSpeed): self return $self; } + /** + * Optional caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters. + * + * @param list $tags + */ + public function withTags(array $tags): self + { + $self = clone $this; + $self['tags'] = $tags; + + return $self; + } + /** * 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). */ @@ -399,8 +436,10 @@ public function withHighConfidenceOnly(bool $highConfidenceOnly): self /** * Optional Merchant Category Code (MCC) to help identify the business category or industry. + * + * @param MccShape $mcc */ - public function withMcc(int $mcc): self + public function withMcc(string|float $mcc): self { $self = clone $this; $self['mcc'] = $mcc; @@ -410,8 +449,10 @@ public function withMcc(int $mcc): self /** * Optional phone number from the transaction to help verify brand match. + * + * @param PhoneShape $phone */ - public function withPhone(float $phone): self + public function withPhone(string|float $phone): self { $self = clone $this; $self['phone'] = $phone; diff --git a/src/Brand/BrandRetrieveParams/Mcc.php b/src/Brand/BrandRetrieveParams/Mcc.php new file mode 100644 index 0000000..4283cea --- /dev/null +++ b/src/Brand/BrandRetrieveParams/Mcc.php @@ -0,0 +1,28 @@ +|array + */ + public static function variants(): array + { + return ['string', 'float']; + } +} diff --git a/src/Brand/BrandRetrieveParams/Phone.php b/src/Brand/BrandRetrieveParams/Phone.php new file mode 100644 index 0000000..ce11b2b --- /dev/null +++ b/src/Brand/BrandRetrieveParams/Phone.php @@ -0,0 +1,28 @@ +|array + */ + public static function variants(): array + { + return ['string', 'float']; + } +} diff --git a/src/Brand/BrandRetrieveSimplifiedParams.php b/src/Brand/BrandRetrieveSimplifiedParams.php index f102491..00df348 100644 --- a/src/Brand/BrandRetrieveSimplifiedParams.php +++ b/src/Brand/BrandRetrieveSimplifiedParams.php @@ -4,6 +4,7 @@ namespace ContextDev\Brand; +use ContextDev\Brand\BrandRetrieveSimplifiedParams\Theme; use ContextDev\Core\Attributes\Optional; use ContextDev\Core\Attributes\Required; use ContextDev\Core\Concerns\SdkModel; @@ -16,7 +17,11 @@ * @see ContextDev\Services\BrandService::retrieveSimplified() * * @phpstan-type BrandRetrieveSimplifiedParamsShape = array{ - * domain: string, maxAgeMs?: int|null, timeoutMs?: int|null + * domain: string, + * maxAgeMs?: int|null, + * tags?: list|null, + * theme?: null|Theme|value-of, + * timeoutMs?: int|null, * } */ final class BrandRetrieveSimplifiedParams implements BaseModel @@ -34,9 +39,25 @@ final class BrandRetrieveSimplifiedParams implements BaseModel /** * Maximum age in milliseconds for cached brand 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. */ - #[Optional] + #[Optional(nullable: true)] public ?int $maxAgeMs; + /** + * Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters. + * + * @var list|null $tags + */ + #[Optional(list: 'string')] + public ?array $tags; + + /** + * Optional theme preference used when selecting brand assets. + * + * @var value-of|null $theme + */ + #[Optional(enum: Theme::class)] + public ?string $theme; + /** * 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). */ @@ -66,17 +87,24 @@ public function __construct() * Construct an instance from the required parameters. * * You must use named parameters to construct any parameters with a default value. + * + * @param list|null $tags + * @param Theme|value-of|null $theme */ public static function with( string $domain, ?int $maxAgeMs = null, - ?int $timeoutMs = null + ?array $tags = null, + Theme|string|null $theme = null, + ?int $timeoutMs = null, ): self { $self = new self; $self['domain'] = $domain; null !== $maxAgeMs && $self['maxAgeMs'] = $maxAgeMs; + null !== $tags && $self['tags'] = $tags; + null !== $theme && $self['theme'] = $theme; null !== $timeoutMs && $self['timeoutMs'] = $timeoutMs; return $self; @@ -96,7 +124,7 @@ public function withDomain(string $domain): self /** * Maximum age in milliseconds for cached brand 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. */ - public function withMaxAgeMs(int $maxAgeMs): self + public function withMaxAgeMs(?int $maxAgeMs): self { $self = clone $this; $self['maxAgeMs'] = $maxAgeMs; @@ -104,6 +132,32 @@ public function withMaxAgeMs(int $maxAgeMs): self return $self; } + /** + * Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters. + * + * @param list $tags + */ + public function withTags(array $tags): self + { + $self = clone $this; + $self['tags'] = $tags; + + return $self; + } + + /** + * Optional theme preference used when selecting brand assets. + * + * @param Theme|value-of $theme + */ + public function withTheme(Theme|string $theme): self + { + $self = clone $this; + $self['theme'] = $theme; + + return $self; + } + /** * 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). */ diff --git a/src/Brand/BrandRetrieveSimplifiedParams/Theme.php b/src/Brand/BrandRetrieveSimplifiedParams/Theme.php new file mode 100644 index 0000000..55e9cac --- /dev/null +++ b/src/Brand/BrandRetrieveSimplifiedParams/Theme.php @@ -0,0 +1,15 @@ +|null, * timeoutMs?: int|null, * } */ @@ -46,6 +47,14 @@ final class IndustryRetrieveNaicsParams implements BaseModel #[Optional] public ?int $minResults; + /** + * Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters. + * + * @var list|null $tags + */ + #[Optional(list: 'string')] + public ?array $tags; + /** * 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). */ @@ -75,11 +84,14 @@ public function __construct() * Construct an instance from the required parameters. * * You must use named parameters to construct any parameters with a default value. + * + * @param list|null $tags */ public static function with( string $input, ?int $maxResults = null, ?int $minResults = null, + ?array $tags = null, ?int $timeoutMs = null, ): self { $self = new self; @@ -88,6 +100,7 @@ public static function with( null !== $maxResults && $self['maxResults'] = $maxResults; null !== $minResults && $self['minResults'] = $minResults; + null !== $tags && $self['tags'] = $tags; null !== $timeoutMs && $self['timeoutMs'] = $timeoutMs; return $self; @@ -126,6 +139,19 @@ public function withMinResults(int $minResults): self return $self; } + /** + * Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters. + * + * @param list $tags + */ + public function withTags(array $tags): self + { + $self = clone $this; + $self['tags'] = $tags; + + return $self; + } + /** * 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). */ diff --git a/src/Industry/IndustryRetrieveSicParams.php b/src/Industry/IndustryRetrieveSicParams.php index 97aece5..be461f4 100644 --- a/src/Industry/IndustryRetrieveSicParams.php +++ b/src/Industry/IndustryRetrieveSicParams.php @@ -20,6 +20,7 @@ * input: string, * maxResults?: int|null, * minResults?: int|null, + * tags?: list|null, * timeoutMs?: int|null, * type?: null|Type|value-of, * } @@ -48,6 +49,14 @@ final class IndustryRetrieveSicParams implements BaseModel #[Optional] public ?int $minResults; + /** + * Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters. + * + * @var list|null $tags + */ + #[Optional(list: 'string')] + public ?array $tags; + /** * 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). */ @@ -86,12 +95,14 @@ public function __construct() * * You must use named parameters to construct any parameters with a default value. * + * @param list|null $tags * @param Type|value-of|null $type */ public static function with( string $input, ?int $maxResults = null, ?int $minResults = null, + ?array $tags = null, ?int $timeoutMs = null, Type|string|null $type = null, ): self { @@ -101,6 +112,7 @@ public static function with( null !== $maxResults && $self['maxResults'] = $maxResults; null !== $minResults && $self['minResults'] = $minResults; + null !== $tags && $self['tags'] = $tags; null !== $timeoutMs && $self['timeoutMs'] = $timeoutMs; null !== $type && $self['type'] = $type; @@ -140,6 +152,19 @@ public function withMinResults(int $minResults): self return $self; } + /** + * Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters. + * + * @param list $tags + */ + public function withTags(array $tags): self + { + $self = clone $this; + $self['tags'] = $tags; + + return $self; + } + /** * 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). */ diff --git a/src/Monitors/MonitorListAccountChangesParams.php b/src/Monitors/MonitorListAccountChangesParams.php index 53cfc41..23ad91a 100644 --- a/src/Monitors/MonitorListAccountChangesParams.php +++ b/src/Monitors/MonitorListAccountChangesParams.php @@ -33,19 +33,35 @@ final class MonitorListAccountChangesParams implements BaseModel use SdkModel; use SdkParams; - /** @var value-of|null $changeDetectionType */ + /** + * Filter by change detection type. + * + * @var value-of|null $changeDetectionType + */ #[Optional(enum: ChangeDetectionType::class)] public ?string $changeDetectionType; + /** + * Opaque pagination cursor from a previous response. + */ #[Optional] public ?string $cursor; + /** + * Maximum number of items to return per page (1-100). Defaults to 25. + */ #[Optional] public ?int $limit; + /** + * Filter changes to a single monitor. + */ #[Optional] public ?string $monitorID; + /** + * Only include items at or after this ISO 8601 timestamp. + */ #[Optional] public ?\DateTimeInterface $since; @@ -55,10 +71,17 @@ final class MonitorListAccountChangesParams implements BaseModel #[Optional] public ?string $tag; - /** @var value-of|null $targetType */ + /** + * Filter by target type. + * + * @var value-of|null $targetType + */ #[Optional(enum: TargetType::class)] public ?string $targetType; + /** + * Only include items before this ISO 8601 timestamp. + */ #[Optional] public ?\DateTimeInterface $until; @@ -100,6 +123,8 @@ public static function with( } /** + * Filter by change detection type. + * * @param ChangeDetectionType|value-of $changeDetectionType */ public function withChangeDetectionType( @@ -111,6 +136,9 @@ public function withChangeDetectionType( return $self; } + /** + * Opaque pagination cursor from a previous response. + */ public function withCursor(string $cursor): self { $self = clone $this; @@ -119,6 +147,9 @@ public function withCursor(string $cursor): self return $self; } + /** + * Maximum number of items to return per page (1-100). Defaults to 25. + */ public function withLimit(int $limit): self { $self = clone $this; @@ -127,6 +158,9 @@ public function withLimit(int $limit): self return $self; } + /** + * Filter changes to a single monitor. + */ public function withMonitorID(string $monitorID): self { $self = clone $this; @@ -135,6 +169,9 @@ public function withMonitorID(string $monitorID): self return $self; } + /** + * Only include items at or after this ISO 8601 timestamp. + */ public function withSince(\DateTimeInterface $since): self { $self = clone $this; @@ -155,6 +192,8 @@ public function withTag(string $tag): self } /** + * Filter by target type. + * * @param TargetType|value-of $targetType */ public function withTargetType(TargetType|string $targetType): self @@ -165,6 +204,9 @@ public function withTargetType(TargetType|string $targetType): self return $self; } + /** + * Only include items before this ISO 8601 timestamp. + */ public function withUntil(\DateTimeInterface $until): self { $self = clone $this; diff --git a/src/Monitors/MonitorListAccountChangesParams/ChangeDetectionType.php b/src/Monitors/MonitorListAccountChangesParams/ChangeDetectionType.php index 6890569..671180e 100644 --- a/src/Monitors/MonitorListAccountChangesParams/ChangeDetectionType.php +++ b/src/Monitors/MonitorListAccountChangesParams/ChangeDetectionType.php @@ -4,6 +4,9 @@ namespace ContextDev\Monitors\MonitorListAccountChangesParams; +/** + * Filter by change detection type. + */ enum ChangeDetectionType: string { case EXACT = 'exact'; diff --git a/src/Monitors/MonitorListAccountChangesParams/TargetType.php b/src/Monitors/MonitorListAccountChangesParams/TargetType.php index e627d0d..df58ce6 100644 --- a/src/Monitors/MonitorListAccountChangesParams/TargetType.php +++ b/src/Monitors/MonitorListAccountChangesParams/TargetType.php @@ -4,6 +4,9 @@ namespace ContextDev\Monitors\MonitorListAccountChangesParams; +/** + * Filter by target type. + */ enum TargetType: string { case PAGE = 'page'; diff --git a/src/Monitors/MonitorListAccountRunsParams.php b/src/Monitors/MonitorListAccountRunsParams.php index 474613e..c1e85d8 100644 --- a/src/Monitors/MonitorListAccountRunsParams.php +++ b/src/Monitors/MonitorListAccountRunsParams.php @@ -25,14 +25,20 @@ final class MonitorListAccountRunsParams implements BaseModel use SdkModel; use SdkParams; + /** + * Opaque pagination cursor from a previous response. + */ #[Optional] public ?string $cursor; + /** + * Maximum number of items to return per page (1-100). Defaults to 25. + */ #[Optional] public ?int $limit; /** - * Lifecycle status of a run. `skipped` runs never executed — see `skip_reason` (insufficient credits, monitor paused, or superseded by a concurrent run). + * Filter runs by lifecycle status. * * @var value-of|null $status */ @@ -65,6 +71,9 @@ public static function with( return $self; } + /** + * Opaque pagination cursor from a previous response. + */ public function withCursor(string $cursor): self { $self = clone $this; @@ -73,6 +82,9 @@ public function withCursor(string $cursor): self return $self; } + /** + * Maximum number of items to return per page (1-100). Defaults to 25. + */ public function withLimit(int $limit): self { $self = clone $this; @@ -82,7 +94,7 @@ public function withLimit(int $limit): self } /** - * Lifecycle status of a run. `skipped` runs never executed — see `skip_reason` (insufficient credits, monitor paused, or superseded by a concurrent run). + * Filter runs by lifecycle status. * * @param Status|value-of $status */ diff --git a/src/Monitors/MonitorListAccountRunsParams/Status.php b/src/Monitors/MonitorListAccountRunsParams/Status.php index 585dc95..b710283 100644 --- a/src/Monitors/MonitorListAccountRunsParams/Status.php +++ b/src/Monitors/MonitorListAccountRunsParams/Status.php @@ -5,7 +5,7 @@ namespace ContextDev\Monitors\MonitorListAccountRunsParams; /** - * Lifecycle status of a run. `skipped` runs never executed — see `skip_reason` (insufficient credits, monitor paused, or superseded by a concurrent run). + * Filter runs by lifecycle status. */ enum Status: string { diff --git a/src/Monitors/MonitorListAccountRunsResponse/Data.php b/src/Monitors/MonitorListAccountRunsResponse/Data.php index a73960d..f87eef4 100644 --- a/src/Monitors/MonitorListAccountRunsResponse/Data.php +++ b/src/Monitors/MonitorListAccountRunsResponse/Data.php @@ -14,11 +14,13 @@ use ContextDev\Monitors\MonitorListAccountRunsResponse\Data\SkipReason; use ContextDev\Monitors\MonitorListAccountRunsResponse\Data\Status; use ContextDev\Monitors\MonitorListAccountRunsResponse\Data\TargetType; -use ContextDev\Monitors\WebhookDelivery; +use ContextDev\Monitors\MonitorListAccountRunsResponse\Data\WebhookDelivery; +use ContextDev\Monitors\MonitorListAccountRunsResponse\Data\WebhookDelivery1; /** * @phpstan-import-type ErrorShape from \ContextDev\Monitors\MonitorListAccountRunsResponse\Data\Error - * @phpstan-import-type WebhookDeliveryShape from \ContextDev\Monitors\WebhookDelivery + * @phpstan-import-type WebhookDelivery1Shape from \ContextDev\Monitors\MonitorListAccountRunsResponse\Data\WebhookDelivery1 + * @phpstan-import-type WebhookDeliveryShape from \ContextDev\Monitors\MonitorListAccountRunsResponse\Data\WebhookDelivery * * @phpstan-type DataShape = array{ * id: string, @@ -35,7 +37,7 @@ * error?: null|Error|ErrorShape, * skipReason?: null|SkipReason|value-of, * startedAt?: \DateTimeInterface|null, - * webhookDeliveries?: list|null, + * webhookDeliveries?: list|null, * webhookDelivery?: null|WebhookDelivery|WebhookDeliveryShape, * } */ @@ -112,9 +114,9 @@ final class Data implements BaseModel /** * All webhook deliveries attempted by this run — one per subscribed event that fired. Omitted when no webhook was attempted, including runs created before event selection was added. * - * @var list|null $webhookDeliveries + * @var list|null $webhookDeliveries */ - #[Optional('webhook_deliveries', list: WebhookDelivery::class)] + #[Optional('webhook_deliveries', list: WebhookDelivery1::class)] public ?array $webhookDeliveries; /** @@ -174,7 +176,7 @@ public function __construct() * @param TargetType|value-of $targetType * @param Error|ErrorShape|null $error * @param SkipReason|value-of|null $skipReason - * @param list|null $webhookDeliveries + * @param list|null $webhookDeliveries * @param WebhookDelivery|WebhookDeliveryShape|null $webhookDelivery */ public static function with( @@ -364,7 +366,7 @@ public function withStartedAt(?\DateTimeInterface $startedAt): self /** * All webhook deliveries attempted by this run — one per subscribed event that fired. Omitted when no webhook was attempted, including runs created before event selection was added. * - * @param list $webhookDeliveries + * @param list $webhookDeliveries */ public function withWebhookDeliveries(array $webhookDeliveries): self { diff --git a/src/Monitors/MonitorListAccountRunsResponse/Data/WebhookDelivery.php b/src/Monitors/MonitorListAccountRunsResponse/Data/WebhookDelivery.php new file mode 100644 index 0000000..77fd214 --- /dev/null +++ b/src/Monitors/MonitorListAccountRunsResponse/Data/WebhookDelivery.php @@ -0,0 +1,200 @@ +, + * eventID: string, + * httpStatus: int|null, + * status: \ContextDev\Monitors\MonitorListAccountRunsResponse\Data\WebhookDelivery\Status|value-of<\ContextDev\Monitors\MonitorListAccountRunsResponse\Data\WebhookDelivery\Status>, + * } + */ +final class WebhookDelivery implements BaseModel +{ + /** @use SdkModel */ + use SdkModel; + + #[Required('attempted_at')] + public \DateTimeInterface $attemptedAt; + + #[Required] + public ?Error $error; + + /** + * The event this delivery carried. Deliveries recorded before event selection existed report change.detected. + * + * @var value-of $event + */ + #[Required(enum: Event::class)] + public string $event; + + /** + * Identifier sent in the X-Context-Id header. + */ + #[Required('event_id')] + public string $eventID; + + /** + * The endpoint's final HTTP response status, or null when no response was received. + */ + #[Required('http_status')] + public ?int $httpStatus; + + /** + * 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. + * + * @var value-of $status + */ + #[Required( + enum: Status::class, + )] + public string $status; + + /** + * `new WebhookDelivery()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * WebhookDelivery::with( + * attemptedAt: ..., + * error: ..., + * event: ..., + * eventID: ..., + * httpStatus: ..., + * status: ..., + * ) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new WebhookDelivery) + * ->withAttemptedAt(...) + * ->withError(...) + * ->withEvent(...) + * ->withEventID(...) + * ->withHTTPStatus(...) + * ->withStatus(...) + * ``` + */ + 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. + * + * @param Error|ErrorShape|null $error + * @param Event|value-of $event + * @param Status|value-of $status + */ + public static function with( + \DateTimeInterface $attemptedAt, + Error|array|null $error, + Event|string $event, + string $eventID, + ?int $httpStatus, + Status|string $status, + ): self { + $self = new self; + + $self['attemptedAt'] = $attemptedAt; + $self['error'] = $error; + $self['event'] = $event; + $self['eventID'] = $eventID; + $self['httpStatus'] = $httpStatus; + $self['status'] = $status; + + return $self; + } + + public function withAttemptedAt(\DateTimeInterface $attemptedAt): self + { + $self = clone $this; + $self['attemptedAt'] = $attemptedAt; + + return $self; + } + + /** + * @param Error|ErrorShape|null $error + */ + public function withError( + Error|array|null $error, + ): self { + $self = clone $this; + $self['error'] = $error; + + return $self; + } + + /** + * The event this delivery carried. Deliveries recorded before event selection existed report change.detected. + * + * @param Event|value-of $event + */ + public function withEvent(Event|string $event): self + { + $self = clone $this; + $self['event'] = $event; + + return $self; + } + + /** + * Identifier sent in the X-Context-Id header. + */ + public function withEventID(string $eventID): self + { + $self = clone $this; + $self['eventID'] = $eventID; + + return $self; + } + + /** + * The endpoint's final HTTP response status, or null when no response was received. + */ + public function withHTTPStatus(?int $httpStatus): self + { + $self = clone $this; + $self['httpStatus'] = $httpStatus; + + return $self; + } + + /** + * 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. + * + * @param Status|value-of $status + */ + public function withStatus( + Status|string $status, + ): self { + $self = clone $this; + $self['status'] = $status; + + return $self; + } +} diff --git a/src/Monitors/MonitorListAccountRunsResponse/Data/WebhookDelivery/Error.php b/src/Monitors/MonitorListAccountRunsResponse/Data/WebhookDelivery/Error.php new file mode 100644 index 0000000..951e5b2 --- /dev/null +++ b/src/Monitors/MonitorListAccountRunsResponse/Data/WebhookDelivery/Error.php @@ -0,0 +1,74 @@ + */ + use SdkModel; + + #[Required] + public string $code; + + #[Required] + public string $message; + + /** + * `new Error()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * Error::with(code: ..., message: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new Error)->withCode(...)->withMessage(...) + * ``` + */ + 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(string $code, string $message): self + { + $self = new self; + + $self['code'] = $code; + $self['message'] = $message; + + return $self; + } + + public function withCode(string $code): self + { + $self = clone $this; + $self['code'] = $code; + + return $self; + } + + public function withMessage(string $message): self + { + $self = clone $this; + $self['message'] = $message; + + return $self; + } +} diff --git a/src/Monitors/MonitorListAccountRunsResponse/Data/WebhookDelivery/Event.php b/src/Monitors/MonitorListAccountRunsResponse/Data/WebhookDelivery/Event.php new file mode 100644 index 0000000..dab594a --- /dev/null +++ b/src/Monitors/MonitorListAccountRunsResponse/Data/WebhookDelivery/Event.php @@ -0,0 +1,15 @@ +, + * eventID: string, + * httpStatus: int|null, + * status: \ContextDev\Monitors\MonitorListAccountRunsResponse\Data\WebhookDelivery1\Status|value-of<\ContextDev\Monitors\MonitorListAccountRunsResponse\Data\WebhookDelivery1\Status>, + * } + */ +final class WebhookDelivery1 implements BaseModel +{ + /** @use SdkModel */ + use SdkModel; + + #[Required('attempted_at')] + public \DateTimeInterface $attemptedAt; + + #[Required] + public ?Error $error; + + /** + * The event this delivery carried. Deliveries recorded before event selection existed report change.detected. + * + * @var value-of $event + */ + #[Required(enum: Event::class)] + public string $event; + + /** + * Identifier sent in the X-Context-Id header. + */ + #[Required('event_id')] + public string $eventID; + + /** + * The endpoint's final HTTP response status, or null when no response was received. + */ + #[Required('http_status')] + public ?int $httpStatus; + + /** + * 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. + * + * @var value-of $status + */ + #[Required( + enum: Status::class, + )] + public string $status; + + /** + * `new WebhookDelivery1()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * WebhookDelivery1::with( + * attemptedAt: ..., + * error: ..., + * event: ..., + * eventID: ..., + * httpStatus: ..., + * status: ..., + * ) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new WebhookDelivery1) + * ->withAttemptedAt(...) + * ->withError(...) + * ->withEvent(...) + * ->withEventID(...) + * ->withHTTPStatus(...) + * ->withStatus(...) + * ``` + */ + 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. + * + * @param Error|ErrorShape|null $error + * @param Event|value-of $event + * @param Status|value-of $status + */ + public static function with( + \DateTimeInterface $attemptedAt, + Error|array|null $error, + Event|string $event, + string $eventID, + ?int $httpStatus, + Status|string $status, + ): self { + $self = new self; + + $self['attemptedAt'] = $attemptedAt; + $self['error'] = $error; + $self['event'] = $event; + $self['eventID'] = $eventID; + $self['httpStatus'] = $httpStatus; + $self['status'] = $status; + + return $self; + } + + public function withAttemptedAt(\DateTimeInterface $attemptedAt): self + { + $self = clone $this; + $self['attemptedAt'] = $attemptedAt; + + return $self; + } + + /** + * @param Error|ErrorShape|null $error + */ + public function withError( + Error|array|null $error, + ): self { + $self = clone $this; + $self['error'] = $error; + + return $self; + } + + /** + * The event this delivery carried. Deliveries recorded before event selection existed report change.detected. + * + * @param Event|value-of $event + */ + public function withEvent(Event|string $event): self + { + $self = clone $this; + $self['event'] = $event; + + return $self; + } + + /** + * Identifier sent in the X-Context-Id header. + */ + public function withEventID(string $eventID): self + { + $self = clone $this; + $self['eventID'] = $eventID; + + return $self; + } + + /** + * The endpoint's final HTTP response status, or null when no response was received. + */ + public function withHTTPStatus(?int $httpStatus): self + { + $self = clone $this; + $self['httpStatus'] = $httpStatus; + + return $self; + } + + /** + * 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. + * + * @param Status|value-of $status + */ + public function withStatus( + Status|string $status, + ): self { + $self = clone $this; + $self['status'] = $status; + + return $self; + } +} diff --git a/src/Monitors/MonitorListAccountRunsResponse/Data/WebhookDelivery1/Error.php b/src/Monitors/MonitorListAccountRunsResponse/Data/WebhookDelivery1/Error.php new file mode 100644 index 0000000..96919d8 --- /dev/null +++ b/src/Monitors/MonitorListAccountRunsResponse/Data/WebhookDelivery1/Error.php @@ -0,0 +1,74 @@ + */ + use SdkModel; + + #[Required] + public string $code; + + #[Required] + public string $message; + + /** + * `new Error()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * Error::with(code: ..., message: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new Error)->withCode(...)->withMessage(...) + * ``` + */ + 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(string $code, string $message): self + { + $self = new self; + + $self['code'] = $code; + $self['message'] = $message; + + return $self; + } + + public function withCode(string $code): self + { + $self = clone $this; + $self['code'] = $code; + + return $self; + } + + public function withMessage(string $message): self + { + $self = clone $this; + $self['message'] = $message; + + return $self; + } +} diff --git a/src/Monitors/MonitorListAccountRunsResponse/Data/WebhookDelivery1/Event.php b/src/Monitors/MonitorListAccountRunsResponse/Data/WebhookDelivery1/Event.php new file mode 100644 index 0000000..b797184 --- /dev/null +++ b/src/Monitors/MonitorListAccountRunsResponse/Data/WebhookDelivery1/Event.php @@ -0,0 +1,15 @@ +|null $changeDetectionType */ + /** + * Filter by change detection type. + * + * @var value-of|null $changeDetectionType + */ #[Optional(enum: ChangeDetectionType::class)] public ?string $changeDetectionType; + /** + * Opaque pagination cursor from a previous response. + */ #[Optional] public ?string $cursor; + /** + * Maximum number of items to return per page (1-100). Defaults to 25. + */ #[Optional] public ?int $limit; @@ -59,7 +69,7 @@ final class MonitorListParams implements BaseModel * * @var list>|null $searchBy */ - #[Optional(list: SearchBy::class)] + #[Optional(list: SearchBy::class, nullable: true)] public ?array $searchBy; /** @@ -71,7 +81,7 @@ final class MonitorListParams implements BaseModel public ?string $searchType; /** - * Monitor lifecycle status. `failed` means the most recent run failed (see the monitor's `last_error`); failed monitors keep running on schedule and flip back to `active` on the next successful run. Monitors are auto-`paused` after repeated consecutive failures or insufficient-credit skips; resume by PATCHing status to `active`. + * Filter monitors by lifecycle status. * * @var value-of|null $status */ @@ -89,10 +99,14 @@ final class MonitorListParams implements BaseModel * * @var list|null $tags */ - #[Optional(list: 'string')] + #[Optional(list: 'string', nullable: true)] public ?array $tags; - /** @var value-of|null $targetType */ + /** + * Filter by target type. + * + * @var value-of|null $targetType + */ #[Optional(enum: TargetType::class)] public ?string $targetType; @@ -142,6 +156,8 @@ public static function with( } /** + * Filter by change detection type. + * * @param ChangeDetectionType|value-of $changeDetectionType */ public function withChangeDetectionType( @@ -153,6 +169,9 @@ public function withChangeDetectionType( return $self; } + /** + * Opaque pagination cursor from a previous response. + */ public function withCursor(string $cursor): self { $self = clone $this; @@ -161,6 +180,9 @@ public function withCursor(string $cursor): self return $self; } + /** + * Maximum number of items to return per page (1-100). Defaults to 25. + */ public function withLimit(int $limit): self { $self = clone $this; @@ -183,9 +205,9 @@ public function withQ(string $q): self /** * Comma-separated fields to search with `q`. Defaults to all of them. Note `instructions` only exists on extract monitors. * - * @param list> $searchBy + * @param list>|null $searchBy */ - public function withSearchBy(array $searchBy): self + public function withSearchBy(?array $searchBy): self { $self = clone $this; $self['searchBy'] = $searchBy; @@ -207,7 +229,7 @@ public function withSearchType(SearchType|string $searchType): self } /** - * Monitor lifecycle status. `failed` means the most recent run failed (see the monitor's `last_error`); failed monitors keep running on schedule and flip back to `active` on the next successful run. Monitors are auto-`paused` after repeated consecutive failures or insufficient-credit skips; resume by PATCHing status to `active`. + * Filter monitors by lifecycle status. * * @param Status|value-of $status */ @@ -233,9 +255,9 @@ public function withTag(string $tag): self /** * Comma-separated list of tags to filter by (matches monitors having any of them). * - * @param list $tags + * @param list|null $tags */ - public function withTags(array $tags): self + public function withTags(?array $tags): self { $self = clone $this; $self['tags'] = $tags; @@ -244,6 +266,8 @@ public function withTags(array $tags): self } /** + * Filter by target type. + * * @param TargetType|value-of $targetType */ public function withTargetType(TargetType|string $targetType): self diff --git a/src/Monitors/MonitorListParams/ChangeDetectionType.php b/src/Monitors/MonitorListParams/ChangeDetectionType.php index d0e2972..51debeb 100644 --- a/src/Monitors/MonitorListParams/ChangeDetectionType.php +++ b/src/Monitors/MonitorListParams/ChangeDetectionType.php @@ -4,6 +4,9 @@ namespace ContextDev\Monitors\MonitorListParams; +/** + * Filter by change detection type. + */ enum ChangeDetectionType: string { case EXACT = 'exact'; diff --git a/src/Monitors/MonitorListParams/Status.php b/src/Monitors/MonitorListParams/Status.php index 84537bd..c675acf 100644 --- a/src/Monitors/MonitorListParams/Status.php +++ b/src/Monitors/MonitorListParams/Status.php @@ -5,7 +5,7 @@ namespace ContextDev\Monitors\MonitorListParams; /** - * Monitor lifecycle status. `failed` means the most recent run failed (see the monitor's `last_error`); failed monitors keep running on schedule and flip back to `active` on the next successful run. Monitors are auto-`paused` after repeated consecutive failures or insufficient-credit skips; resume by PATCHing status to `active`. + * Filter monitors by lifecycle status. */ enum Status: string { diff --git a/src/Monitors/MonitorListParams/TargetType.php b/src/Monitors/MonitorListParams/TargetType.php index d41270c..442d961 100644 --- a/src/Monitors/MonitorListParams/TargetType.php +++ b/src/Monitors/MonitorListParams/TargetType.php @@ -4,6 +4,9 @@ namespace ContextDev\Monitors\MonitorListParams; +/** + * Filter by target type. + */ enum TargetType: string { case PAGE = 'page'; diff --git a/src/Monitors/MonitorListRunsParams.php b/src/Monitors/MonitorListRunsParams.php index 8b87f69..a2161eb 100644 --- a/src/Monitors/MonitorListRunsParams.php +++ b/src/Monitors/MonitorListRunsParams.php @@ -25,14 +25,20 @@ final class MonitorListRunsParams implements BaseModel use SdkModel; use SdkParams; + /** + * Opaque pagination cursor from a previous response. + */ #[Optional] public ?string $cursor; + /** + * Maximum number of items to return per page (1-100). Defaults to 25. + */ #[Optional] public ?int $limit; /** - * Lifecycle status of a run. `skipped` runs never executed — see `skip_reason` (insufficient credits, monitor paused, or superseded by a concurrent run). + * Filter runs by lifecycle status. * * @var value-of|null $status */ @@ -65,6 +71,9 @@ public static function with( return $self; } + /** + * Opaque pagination cursor from a previous response. + */ public function withCursor(string $cursor): self { $self = clone $this; @@ -73,6 +82,9 @@ public function withCursor(string $cursor): self return $self; } + /** + * Maximum number of items to return per page (1-100). Defaults to 25. + */ public function withLimit(int $limit): self { $self = clone $this; @@ -82,7 +94,7 @@ public function withLimit(int $limit): self } /** - * Lifecycle status of a run. `skipped` runs never executed — see `skip_reason` (insufficient credits, monitor paused, or superseded by a concurrent run). + * Filter runs by lifecycle status. * * @param Status|value-of $status */ diff --git a/src/Monitors/MonitorListRunsParams/Status.php b/src/Monitors/MonitorListRunsParams/Status.php index 765a444..7863eb6 100644 --- a/src/Monitors/MonitorListRunsParams/Status.php +++ b/src/Monitors/MonitorListRunsParams/Status.php @@ -5,7 +5,7 @@ namespace ContextDev\Monitors\MonitorListRunsParams; /** - * Lifecycle status of a run. `skipped` runs never executed — see `skip_reason` (insufficient credits, monitor paused, or superseded by a concurrent run). + * Filter runs by lifecycle status. */ enum Status: string { diff --git a/src/Monitors/MonitorListRunsResponse/Data.php b/src/Monitors/MonitorListRunsResponse/Data.php index b521dcd..c262135 100644 --- a/src/Monitors/MonitorListRunsResponse/Data.php +++ b/src/Monitors/MonitorListRunsResponse/Data.php @@ -14,11 +14,13 @@ use ContextDev\Monitors\MonitorListRunsResponse\Data\SkipReason; use ContextDev\Monitors\MonitorListRunsResponse\Data\Status; use ContextDev\Monitors\MonitorListRunsResponse\Data\TargetType; -use ContextDev\Monitors\WebhookDelivery; +use ContextDev\Monitors\MonitorListRunsResponse\Data\WebhookDelivery; +use ContextDev\Monitors\MonitorListRunsResponse\Data\WebhookDelivery1; /** * @phpstan-import-type ErrorShape from \ContextDev\Monitors\MonitorListRunsResponse\Data\Error - * @phpstan-import-type WebhookDeliveryShape from \ContextDev\Monitors\WebhookDelivery + * @phpstan-import-type WebhookDelivery1Shape from \ContextDev\Monitors\MonitorListRunsResponse\Data\WebhookDelivery1 + * @phpstan-import-type WebhookDeliveryShape from \ContextDev\Monitors\MonitorListRunsResponse\Data\WebhookDelivery * * @phpstan-type DataShape = array{ * id: string, @@ -35,7 +37,7 @@ * error?: null|Error|ErrorShape, * skipReason?: null|SkipReason|value-of, * startedAt?: \DateTimeInterface|null, - * webhookDeliveries?: list|null, + * webhookDeliveries?: list|null, * webhookDelivery?: null|WebhookDelivery|WebhookDeliveryShape, * } */ @@ -112,9 +114,9 @@ final class Data implements BaseModel /** * All webhook deliveries attempted by this run — one per subscribed event that fired. Omitted when no webhook was attempted, including runs created before event selection was added. * - * @var list|null $webhookDeliveries + * @var list|null $webhookDeliveries */ - #[Optional('webhook_deliveries', list: WebhookDelivery::class)] + #[Optional('webhook_deliveries', list: WebhookDelivery1::class)] public ?array $webhookDeliveries; /** @@ -174,7 +176,7 @@ public function __construct() * @param TargetType|value-of $targetType * @param Error|ErrorShape|null $error * @param SkipReason|value-of|null $skipReason - * @param list|null $webhookDeliveries + * @param list|null $webhookDeliveries * @param WebhookDelivery|WebhookDeliveryShape|null $webhookDelivery */ public static function with( @@ -364,7 +366,7 @@ public function withStartedAt(?\DateTimeInterface $startedAt): self /** * All webhook deliveries attempted by this run — one per subscribed event that fired. Omitted when no webhook was attempted, including runs created before event selection was added. * - * @param list $webhookDeliveries + * @param list $webhookDeliveries */ public function withWebhookDeliveries(array $webhookDeliveries): self { diff --git a/src/Monitors/WebhookDelivery.php b/src/Monitors/MonitorListRunsResponse/Data/WebhookDelivery.php similarity index 79% rename from src/Monitors/WebhookDelivery.php rename to src/Monitors/MonitorListRunsResponse/Data/WebhookDelivery.php index 8e85e19..bea65e0 100644 --- a/src/Monitors/WebhookDelivery.php +++ b/src/Monitors/MonitorListRunsResponse/Data/WebhookDelivery.php @@ -2,25 +2,29 @@ declare(strict_types=1); -namespace ContextDev\Monitors; +namespace ContextDev\Monitors\MonitorListRunsResponse\Data; use ContextDev\Core\Attributes\Required; use ContextDev\Core\Concerns\SdkModel; use ContextDev\Core\Contracts\BaseModel; -use ContextDev\Monitors\WebhookDelivery\Error; -use ContextDev\Monitors\WebhookDelivery\Event; -use ContextDev\Monitors\WebhookDelivery\Status; +use ContextDev\Monitors\MonitorListRunsResponse\Data\WebhookDelivery\Error; +use ContextDev\Monitors\MonitorListRunsResponse\Data\WebhookDelivery\Event; +use ContextDev\Monitors\MonitorListRunsResponse\Data\WebhookDelivery\Status; /** - * @phpstan-import-type ErrorShape from \ContextDev\Monitors\WebhookDelivery\Error + * Deprecated: use `webhook_deliveries`, which records every attempt now that a run can deliver multiple events. Omitted when no webhook was attempted, including historical runs created before delivery tracking was added. + * + * @deprecated + * + * @phpstan-import-type ErrorShape from \ContextDev\Monitors\MonitorListRunsResponse\Data\WebhookDelivery\Error * * @phpstan-type WebhookDeliveryShape = array{ * attemptedAt: \DateTimeInterface, - * error: null|Error|ErrorShape, + * error: null|\ContextDev\Monitors\MonitorListRunsResponse\Data\WebhookDelivery\Error|ErrorShape, * event: Event|value-of, * eventID: string, * httpStatus: int|null, - * status: Status|value-of, + * status: \ContextDev\Monitors\MonitorListRunsResponse\Data\WebhookDelivery\Status|value-of<\ContextDev\Monitors\MonitorListRunsResponse\Data\WebhookDelivery\Status>, * } */ final class WebhookDelivery implements BaseModel @@ -59,7 +63,9 @@ final class WebhookDelivery implements BaseModel * * @var value-of $status */ - #[Required(enum: Status::class)] + #[Required( + enum: Status::class, + )] public string $status; /** @@ -134,8 +140,9 @@ public function withAttemptedAt(\DateTimeInterface $attemptedAt): self /** * @param Error|ErrorShape|null $error */ - public function withError(Error|array|null $error): self - { + public function withError( + Error|array|null $error, + ): self { $self = clone $this; $self['error'] = $error; @@ -182,8 +189,9 @@ public function withHTTPStatus(?int $httpStatus): self * * @param Status|value-of $status */ - public function withStatus(Status|string $status): self - { + public function withStatus( + Status|string $status, + ): self { $self = clone $this; $self['status'] = $status; diff --git a/src/Monitors/WebhookDelivery/Error.php b/src/Monitors/MonitorListRunsResponse/Data/WebhookDelivery/Error.php similarity index 95% rename from src/Monitors/WebhookDelivery/Error.php rename to src/Monitors/MonitorListRunsResponse/Data/WebhookDelivery/Error.php index 41d7b9c..16f73be 100644 --- a/src/Monitors/WebhookDelivery/Error.php +++ b/src/Monitors/MonitorListRunsResponse/Data/WebhookDelivery/Error.php @@ -2,7 +2,7 @@ declare(strict_types=1); -namespace ContextDev\Monitors\WebhookDelivery; +namespace ContextDev\Monitors\MonitorListRunsResponse\Data\WebhookDelivery; use ContextDev\Core\Attributes\Required; use ContextDev\Core\Concerns\SdkModel; diff --git a/src/Monitors/WebhookDelivery/Event.php b/src/Monitors/MonitorListRunsResponse/Data/WebhookDelivery/Event.php similarity index 77% rename from src/Monitors/WebhookDelivery/Event.php rename to src/Monitors/MonitorListRunsResponse/Data/WebhookDelivery/Event.php index cc3d58f..b387c98 100644 --- a/src/Monitors/WebhookDelivery/Event.php +++ b/src/Monitors/MonitorListRunsResponse/Data/WebhookDelivery/Event.php @@ -2,7 +2,7 @@ declare(strict_types=1); -namespace ContextDev\Monitors\WebhookDelivery; +namespace ContextDev\Monitors\MonitorListRunsResponse\Data\WebhookDelivery; /** * The event this delivery carried. Deliveries recorded before event selection existed report change.detected. diff --git a/src/Monitors/WebhookDelivery/Status.php b/src/Monitors/MonitorListRunsResponse/Data/WebhookDelivery/Status.php similarity index 84% rename from src/Monitors/WebhookDelivery/Status.php rename to src/Monitors/MonitorListRunsResponse/Data/WebhookDelivery/Status.php index bea3492..af5edb3 100644 --- a/src/Monitors/WebhookDelivery/Status.php +++ b/src/Monitors/MonitorListRunsResponse/Data/WebhookDelivery/Status.php @@ -2,7 +2,7 @@ declare(strict_types=1); -namespace ContextDev\Monitors\WebhookDelivery; +namespace ContextDev\Monitors\MonitorListRunsResponse\Data\WebhookDelivery; /** * 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. diff --git a/src/Monitors/MonitorListRunsResponse/Data/WebhookDelivery1.php b/src/Monitors/MonitorListRunsResponse/Data/WebhookDelivery1.php new file mode 100644 index 0000000..7c224ea --- /dev/null +++ b/src/Monitors/MonitorListRunsResponse/Data/WebhookDelivery1.php @@ -0,0 +1,196 @@ +, + * eventID: string, + * httpStatus: int|null, + * status: \ContextDev\Monitors\MonitorListRunsResponse\Data\WebhookDelivery1\Status|value-of<\ContextDev\Monitors\MonitorListRunsResponse\Data\WebhookDelivery1\Status>, + * } + */ +final class WebhookDelivery1 implements BaseModel +{ + /** @use SdkModel */ + use SdkModel; + + #[Required('attempted_at')] + public \DateTimeInterface $attemptedAt; + + #[Required] + public ?Error $error; + + /** + * The event this delivery carried. Deliveries recorded before event selection existed report change.detected. + * + * @var value-of $event + */ + #[Required(enum: Event::class)] + public string $event; + + /** + * Identifier sent in the X-Context-Id header. + */ + #[Required('event_id')] + public string $eventID; + + /** + * The endpoint's final HTTP response status, or null when no response was received. + */ + #[Required('http_status')] + public ?int $httpStatus; + + /** + * 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. + * + * @var value-of $status + */ + #[Required( + enum: Status::class, + )] + public string $status; + + /** + * `new WebhookDelivery1()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * WebhookDelivery1::with( + * attemptedAt: ..., + * error: ..., + * event: ..., + * eventID: ..., + * httpStatus: ..., + * status: ..., + * ) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new WebhookDelivery1) + * ->withAttemptedAt(...) + * ->withError(...) + * ->withEvent(...) + * ->withEventID(...) + * ->withHTTPStatus(...) + * ->withStatus(...) + * ``` + */ + 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. + * + * @param Error|ErrorShape|null $error + * @param Event|value-of $event + * @param Status|value-of $status + */ + public static function with( + \DateTimeInterface $attemptedAt, + Error|array|null $error, + Event|string $event, + string $eventID, + ?int $httpStatus, + Status|string $status, + ): self { + $self = new self; + + $self['attemptedAt'] = $attemptedAt; + $self['error'] = $error; + $self['event'] = $event; + $self['eventID'] = $eventID; + $self['httpStatus'] = $httpStatus; + $self['status'] = $status; + + return $self; + } + + public function withAttemptedAt(\DateTimeInterface $attemptedAt): self + { + $self = clone $this; + $self['attemptedAt'] = $attemptedAt; + + return $self; + } + + /** + * @param Error|ErrorShape|null $error + */ + public function withError( + Error|array|null $error, + ): self { + $self = clone $this; + $self['error'] = $error; + + return $self; + } + + /** + * The event this delivery carried. Deliveries recorded before event selection existed report change.detected. + * + * @param Event|value-of $event + */ + public function withEvent(Event|string $event): self + { + $self = clone $this; + $self['event'] = $event; + + return $self; + } + + /** + * Identifier sent in the X-Context-Id header. + */ + public function withEventID(string $eventID): self + { + $self = clone $this; + $self['eventID'] = $eventID; + + return $self; + } + + /** + * The endpoint's final HTTP response status, or null when no response was received. + */ + public function withHTTPStatus(?int $httpStatus): self + { + $self = clone $this; + $self['httpStatus'] = $httpStatus; + + return $self; + } + + /** + * 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. + * + * @param Status|value-of $status + */ + public function withStatus( + Status|string $status, + ): self { + $self = clone $this; + $self['status'] = $status; + + return $self; + } +} diff --git a/src/Monitors/MonitorListRunsResponse/Data/WebhookDelivery1/Error.php b/src/Monitors/MonitorListRunsResponse/Data/WebhookDelivery1/Error.php new file mode 100644 index 0000000..94b8d20 --- /dev/null +++ b/src/Monitors/MonitorListRunsResponse/Data/WebhookDelivery1/Error.php @@ -0,0 +1,74 @@ + */ + use SdkModel; + + #[Required] + public string $code; + + #[Required] + public string $message; + + /** + * `new Error()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * Error::with(code: ..., message: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new Error)->withCode(...)->withMessage(...) + * ``` + */ + 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(string $code, string $message): self + { + $self = new self; + + $self['code'] = $code; + $self['message'] = $message; + + return $self; + } + + public function withCode(string $code): self + { + $self = clone $this; + $self['code'] = $code; + + return $self; + } + + public function withMessage(string $message): self + { + $self = clone $this; + $self['message'] = $message; + + return $self; + } +} diff --git a/src/Monitors/MonitorListRunsResponse/Data/WebhookDelivery1/Event.php b/src/Monitors/MonitorListRunsResponse/Data/WebhookDelivery1/Event.php new file mode 100644 index 0000000..fe9094a --- /dev/null +++ b/src/Monitors/MonitorListRunsResponse/Data/WebhookDelivery1/Event.php @@ -0,0 +1,15 @@ +, - * includeImages?: bool|null, - * includeLinks?: bool|null, - * ocr?: bool|null, + * includeImages?: IncludeImagesShape|null, + * includeLinks?: IncludeLinksShape|null, + * ocr?: OcrShape|null, * pdf?: null|Pdf|PdfShape, - * shortenBase64Images?: bool|null, - * useMainContentOnly?: bool|null, + * shortenBase64Images?: ShortenBase64ImagesShape|null, + * tags?: list|null, + * useMainContentOnly?: UseMainContentOnlyShape|null, * } */ final class ParseHandleParams implements BaseModel @@ -35,7 +53,13 @@ final class ParseHandleParams implements BaseModel use SdkParams; /** - * Optional file extension hint. Case-insensitive; a leading dot is accepted (e.g. ".pdf"). + * Optional client identifier used for usage attribution. + */ + #[Optional] + public ?string $client; + + /** + * Optional file extension hint, such as pdf, docx, xlsx, pptx, html, json, csv, md, py, rtf, jpg, png, or txt. * * @var value-of|null $extension */ @@ -44,39 +68,57 @@ final class ParseHandleParams implements BaseModel /** * Include image references in Markdown output. + * + * @var IncludeImagesVariants|null $includeImages */ - #[Optional] - public ?bool $includeImages; + #[Optional(union: IncludeImages::class)] + public bool|string|null $includeImages; /** * Preserve hyperlinks in Markdown output. + * + * @var IncludeLinksVariants|null $includeLinks */ - #[Optional] - public ?bool $includeLinks; + #[Optional(union: IncludeLinks::class)] + public bool|string|null $includeLinks; /** - * Gates all OCR. When true, PDFs get embedded-image OCR (recognized text inserted at each image's position in page reading order, preserving the text layer; pdf.start/pdf.end limit the page range), scanned PDFs with no text layer get full-document OCR, and raster images get their visible text transcribed. When false, no OCR runs: scanned PDFs may yield no content and images return only format/dimension metadata. Calls where OCR actually runs cost 5 credits instead of 1. + * When true for PDF inputs, detect and OCR images embedded in the selected pages, inserting recognized text at each image's position in page reading order while preserving the PDF text layer. pdf.start/pdf.end limit the inclusive page range. When false, all OCR is disabled, including the automatic scanned-PDF fallback. + * + * @var OcrVariants|null $ocr */ - #[Optional] - public ?bool $ocr; + #[Optional(union: Ocr::class)] + public bool|string|null $ocr; /** - * PDF page-range controls. Use start/end to limit parsing (and OCR when ocr=true) to an inclusive 1-based page range. + * PDF page-range options as a JSON object, e.g. {"start": 2, "end": 5}. */ #[Optional] public ?Pdf $pdf; /** * Shorten base64-encoded image data in the Markdown output. + * + * @var ShortenBase64ImagesVariants|null $shortenBase64Images */ - #[Optional] - public ?bool $shortenBase64Images; + #[Optional(union: ShortenBase64Images::class)] + public bool|string|null $shortenBase64Images; + + /** + * Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters. + * + * @var list|null $tags + */ + #[Optional(list: 'string')] + public ?array $tags; /** * Extract only the main content from HTML-like inputs. + * + * @var UseMainContentOnlyVariants|null $useMainContentOnly */ - #[Optional] - public ?bool $useMainContentOnly; + #[Optional(union: UseMainContentOnly::class)] + public bool|string|null $useMainContentOnly; public function __construct() { @@ -89,32 +131,53 @@ public function __construct() * You must use named parameters to construct any parameters with a default value. * * @param Extension|value-of|null $extension + * @param IncludeImagesShape|null $includeImages + * @param IncludeLinksShape|null $includeLinks + * @param OcrShape|null $ocr * @param Pdf|PdfShape|null $pdf + * @param ShortenBase64ImagesShape|null $shortenBase64Images + * @param list|null $tags + * @param UseMainContentOnlyShape|null $useMainContentOnly */ public static function with( + ?string $client = null, Extension|string|null $extension = null, - ?bool $includeImages = null, - ?bool $includeLinks = null, - ?bool $ocr = null, + bool|UnionMember1|string|null $includeImages = null, + bool|IncludeLinks\UnionMember1|string|null $includeLinks = null, + bool|Ocr\UnionMember1|string|null $ocr = null, Pdf|array|null $pdf = null, - ?bool $shortenBase64Images = null, - ?bool $useMainContentOnly = null, + bool|ShortenBase64Images\UnionMember1|string|null $shortenBase64Images = null, + ?array $tags = null, + bool|UseMainContentOnly\UnionMember1|string|null $useMainContentOnly = null, ): self { $self = new self; + null !== $client && $self['client'] = $client; null !== $extension && $self['extension'] = $extension; null !== $includeImages && $self['includeImages'] = $includeImages; null !== $includeLinks && $self['includeLinks'] = $includeLinks; null !== $ocr && $self['ocr'] = $ocr; null !== $pdf && $self['pdf'] = $pdf; null !== $shortenBase64Images && $self['shortenBase64Images'] = $shortenBase64Images; + null !== $tags && $self['tags'] = $tags; null !== $useMainContentOnly && $self['useMainContentOnly'] = $useMainContentOnly; return $self; } /** - * Optional file extension hint. Case-insensitive; a leading dot is accepted (e.g. ".pdf"). + * Optional client identifier used for usage attribution. + */ + public function withClient(string $client): self + { + $self = clone $this; + $self['client'] = $client; + + return $self; + } + + /** + * Optional file extension hint, such as pdf, docx, xlsx, pptx, html, json, csv, md, py, rtf, jpg, png, or txt. * * @param Extension|value-of $extension */ @@ -128,9 +191,12 @@ public function withExtension(Extension|string $extension): self /** * Include image references in Markdown output. + * + * @param IncludeImagesShape $includeImages */ - public function withIncludeImages(bool $includeImages): self - { + public function withIncludeImages( + bool|UnionMember1|string $includeImages + ): self { $self = clone $this; $self['includeImages'] = $includeImages; @@ -139,9 +205,12 @@ public function withIncludeImages(bool $includeImages): self /** * Preserve hyperlinks in Markdown output. + * + * @param IncludeLinksShape $includeLinks */ - public function withIncludeLinks(bool $includeLinks): self - { + public function withIncludeLinks( + bool|IncludeLinks\UnionMember1|string $includeLinks, + ): self { $self = clone $this; $self['includeLinks'] = $includeLinks; @@ -149,10 +218,13 @@ public function withIncludeLinks(bool $includeLinks): self } /** - * Gates all OCR. When true, PDFs get embedded-image OCR (recognized text inserted at each image's position in page reading order, preserving the text layer; pdf.start/pdf.end limit the page range), scanned PDFs with no text layer get full-document OCR, and raster images get their visible text transcribed. When false, no OCR runs: scanned PDFs may yield no content and images return only format/dimension metadata. Calls where OCR actually runs cost 5 credits instead of 1. + * When true for PDF inputs, detect and OCR images embedded in the selected pages, inserting recognized text at each image's position in page reading order while preserving the PDF text layer. pdf.start/pdf.end limit the inclusive page range. When false, all OCR is disabled, including the automatic scanned-PDF fallback. + * + * @param OcrShape $ocr */ - public function withOcr(bool $ocr): self - { + public function withOcr( + bool|Ocr\UnionMember1|string $ocr + ): self { $self = clone $this; $self['ocr'] = $ocr; @@ -160,7 +232,7 @@ public function withOcr(bool $ocr): self } /** - * PDF page-range controls. Use start/end to limit parsing (and OCR when ocr=true) to an inclusive 1-based page range. + * PDF page-range options as a JSON object, e.g. {"start": 2, "end": 5}. * * @param Pdf|PdfShape $pdf */ @@ -174,9 +246,12 @@ public function withPdf(Pdf|array $pdf): self /** * Shorten base64-encoded image data in the Markdown output. + * + * @param ShortenBase64ImagesShape $shortenBase64Images */ - public function withShortenBase64Images(bool $shortenBase64Images): self - { + public function withShortenBase64Images( + bool|ShortenBase64Images\UnionMember1|string $shortenBase64Images, + ): self { $self = clone $this; $self['shortenBase64Images'] = $shortenBase64Images; @@ -184,10 +259,26 @@ public function withShortenBase64Images(bool $shortenBase64Images): self } /** - * Extract only the main content from HTML-like inputs. + * Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters. + * + * @param list $tags */ - public function withUseMainContentOnly(bool $useMainContentOnly): self + public function withTags(array $tags): self { + $self = clone $this; + $self['tags'] = $tags; + + return $self; + } + + /** + * Extract only the main content from HTML-like inputs. + * + * @param UseMainContentOnlyShape $useMainContentOnly + */ + public function withUseMainContentOnly( + bool|UseMainContentOnly\UnionMember1|string $useMainContentOnly, + ): self { $self = clone $this; $self['useMainContentOnly'] = $useMainContentOnly; diff --git a/src/Parse/ParseHandleParams/Extension.php b/src/Parse/ParseHandleParams/Extension.php index 86293e9..fe705d3 100644 --- a/src/Parse/ParseHandleParams/Extension.php +++ b/src/Parse/ParseHandleParams/Extension.php @@ -5,7 +5,7 @@ namespace ContextDev\Parse\ParseHandleParams; /** - * Optional file extension hint. Case-insensitive; a leading dot is accepted (e.g. ".pdf"). + * Optional file extension hint, such as pdf, docx, xlsx, pptx, html, json, csv, md, py, rtf, jpg, png, or txt. */ enum Extension: string { diff --git a/src/Parse/ParseHandleParams/IncludeImages.php b/src/Parse/ParseHandleParams/IncludeImages.php new file mode 100644 index 0000000..0aeba32 --- /dev/null +++ b/src/Parse/ParseHandleParams/IncludeImages.php @@ -0,0 +1,29 @@ + + * @phpstan-type IncludeImagesShape = IncludeImagesVariants + */ +final class IncludeImages implements ConverterSource +{ + use SdkUnion; + + /** + * @return list|array + */ + public static function variants(): array + { + return ['bool', UnionMember1::class]; + } +} diff --git a/src/Parse/ParseHandleParams/IncludeImages/UnionMember1.php b/src/Parse/ParseHandleParams/IncludeImages/UnionMember1.php new file mode 100644 index 0000000..414b4f4 --- /dev/null +++ b/src/Parse/ParseHandleParams/IncludeImages/UnionMember1.php @@ -0,0 +1,12 @@ + + * @phpstan-type IncludeLinksShape = IncludeLinksVariants + */ +final class IncludeLinks implements ConverterSource +{ + use SdkUnion; + + /** + * @return list|array + */ + public static function variants(): array + { + return ['bool', UnionMember1::class]; + } +} diff --git a/src/Parse/ParseHandleParams/IncludeLinks/UnionMember1.php b/src/Parse/ParseHandleParams/IncludeLinks/UnionMember1.php new file mode 100644 index 0000000..77b25f6 --- /dev/null +++ b/src/Parse/ParseHandleParams/IncludeLinks/UnionMember1.php @@ -0,0 +1,12 @@ + + * @phpstan-type OcrShape = OcrVariants + */ +final class Ocr implements ConverterSource +{ + use SdkUnion; + + /** + * @return list|array + */ + public static function variants(): array + { + return ['bool', UnionMember1::class]; + } +} diff --git a/src/Parse/ParseHandleParams/Ocr/UnionMember1.php b/src/Parse/ParseHandleParams/Ocr/UnionMember1.php new file mode 100644 index 0000000..e1f1eaf --- /dev/null +++ b/src/Parse/ParseHandleParams/Ocr/UnionMember1.php @@ -0,0 +1,12 @@ + + * @phpstan-type ShortenBase64ImagesShape = ShortenBase64ImagesVariants + */ +final class ShortenBase64Images implements ConverterSource +{ + use SdkUnion; + + /** + * @return list|array + */ + public static function variants(): array + { + return ['bool', UnionMember1::class]; + } +} diff --git a/src/Parse/ParseHandleParams/ShortenBase64Images/UnionMember1.php b/src/Parse/ParseHandleParams/ShortenBase64Images/UnionMember1.php new file mode 100644 index 0000000..8d28751 --- /dev/null +++ b/src/Parse/ParseHandleParams/ShortenBase64Images/UnionMember1.php @@ -0,0 +1,12 @@ + + * @phpstan-type UseMainContentOnlyShape = UseMainContentOnlyVariants + */ +final class UseMainContentOnly implements ConverterSource +{ + use SdkUnion; + + /** + * @return list|array + */ + public static function variants(): array + { + return ['bool', UnionMember1::class]; + } +} diff --git a/src/Parse/ParseHandleParams/UseMainContentOnly/UnionMember1.php b/src/Parse/ParseHandleParams/UseMainContentOnly/UnionMember1.php new file mode 100644 index 0000000..af6ff08 --- /dev/null +++ b/src/Parse/ParseHandleParams/UseMainContentOnly/UnionMember1.php @@ -0,0 +1,12 @@ + $tags Optional caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-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 * @@ -27,6 +28,7 @@ interface AIContract public function extractProduct( string $url, int $maxAgeMs = 604800000, + ?array $tags = null, ?int $timeoutMs = null, RequestOptions|array|null $requestOptions = null, ): AIExtractProductResponse; @@ -38,6 +40,7 @@ public function extractProduct( * @param string $directURL a specific URL to use directly as the starting point for extraction without domain resolution * @param int $maxAgeMs Return a cached result if a prior scrape for the same parameters exists and is younger than this many milliseconds. Defaults to 7 days (604800000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh. * @param int $maxProducts maximum number of products to extract + * @param list $tags Optional caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-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 * @@ -48,6 +51,7 @@ public function extractProducts( string $directURL, int $maxAgeMs = 604800000, ?int $maxProducts = null, + ?array $tags = null, ?int $timeoutMs = null, RequestOptions|array|null $requestOptions = null, ): AIExtractProductsResponse; diff --git a/src/ServiceContracts/BrandContract.php b/src/ServiceContracts/BrandContract.php index ca83c91..3ca75ea 100644 --- a/src/ServiceContracts/BrandContract.php +++ b/src/ServiceContracts/BrandContract.php @@ -8,10 +8,13 @@ use ContextDev\Brand\BrandGetSimplifiedResponse; use ContextDev\Brand\BrandRetrieveParams\ForceLanguage; use ContextDev\Brand\BrandRetrieveParams\Type; +use ContextDev\Brand\BrandRetrieveSimplifiedParams\Theme; use ContextDev\Core\Exceptions\APIException; use ContextDev\RequestOptions; /** + * @phpstan-import-type MccShape from \ContextDev\Brand\BrandRetrieveParams\Mcc + * @phpstan-import-type PhoneShape from \ContextDev\Brand\BrandRetrieveParams\Phone * @phpstan-import-type RequestOpts from \ContextDev\RequestOptions */ interface BrandContract @@ -26,16 +29,17 @@ interface BrandContract * @param string $ticker Stock ticker symbol to retrieve brand data for (e.g., 'AAPL'). * @param string $directURL Full http(s) URL to fetch brand data from (e.g., 'https://stripe.com/enterprise'). Only this URL is fetched — not the entire internet. * @param string $transactionInfo transaction information to identify the brand - * @param ForceLanguage|value-of $forceLanguage + * @param ForceLanguage|value-of|null $forceLanguage * @param int $maxAgeMs Maximum age in milliseconds for cached brand 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. * @param bool $maxSpeed Optional parameter to optimize the API call for maximum speed. When set to true, the API will skip time-consuming operations for faster response at the cost of less comprehensive data. + * @param list $tags Optional caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-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 string $countryGl optional country code hint (GL parameter) to specify the country when identifying a transaction * @param string $tickerExchange Optional stock exchange for the ticker. Defaults to NASDAQ if not specified. * @param string $city optional city name to prioritize when searching for the brand * @param bool $highConfidenceOnly when set to true, the API performs additional verification to ensure the identified brand matches the transaction with high confidence - * @param int $mcc optional Merchant Category Code (MCC) to help identify the business category or industry - * @param float $phone optional phone number from the transaction to help verify brand match + * @param MccShape $mcc optional Merchant Category Code (MCC) to help identify the business category or industry + * @param PhoneShape $phone optional phone number from the transaction to help verify brand match * @param RequestOpts|null $requestOptions * * @throws APIException @@ -51,13 +55,14 @@ public function retrieve( ForceLanguage|string|null $forceLanguage = null, ?int $maxAgeMs = null, ?bool $maxSpeed = null, + ?array $tags = null, ?int $timeoutMs = null, ?string $countryGl = null, ?string $tickerExchange = null, ?string $city = null, ?bool $highConfidenceOnly = null, - ?int $mcc = null, - ?float $phone = null, + string|float|null $mcc = null, + string|float|null $phone = null, RequestOptions|array|null $requestOptions = null, ): BrandGetResponse; @@ -65,7 +70,9 @@ public function retrieve( * @api * * @param string $domain Domain name to retrieve simplified brand data for - * @param int $maxAgeMs Maximum age in milliseconds for cached brand 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. + * @param int|null $maxAgeMs Maximum age in milliseconds for cached brand 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. + * @param list $tags Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters. + * @param Theme|value-of $theme optional theme preference used when selecting brand assets * @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 * @@ -73,7 +80,9 @@ public function retrieve( */ public function retrieveSimplified( string $domain, - int $maxAgeMs = 7776000000, + ?int $maxAgeMs = 7776000000, + ?array $tags = null, + Theme|string|null $theme = null, ?int $timeoutMs = null, RequestOptions|array|null $requestOptions = null, ): BrandGetSimplifiedResponse; diff --git a/src/ServiceContracts/IndustryContract.php b/src/ServiceContracts/IndustryContract.php index ebfb48c..6a61aaf 100644 --- a/src/ServiceContracts/IndustryContract.php +++ b/src/ServiceContracts/IndustryContract.php @@ -21,6 +21,7 @@ interface IndustryContract * @param string $input Brand domain or title to retrieve NAICS code for. If a valid domain is provided, it will be used for classification, otherwise, we will search for the brand using the provided title. * @param int $maxResults Maximum number of NAICS codes to return. Must be between 1 and 10. Defaults to 5. * @param int $minResults Minimum number of NAICS codes to return. Must be at least 1. Defaults to 1. + * @param list $tags Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-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 * @@ -30,6 +31,7 @@ public function retrieveNaics( string $input, int $maxResults = 5, int $minResults = 1, + ?array $tags = null, ?int $timeoutMs = null, RequestOptions|array|null $requestOptions = null, ): IndustryGetNaicsResponse; @@ -40,6 +42,7 @@ public function retrieveNaics( * @param string $input Brand domain or title to retrieve SIC code for. If a valid domain is provided, it will be used for classification, otherwise, we will search for the brand using the provided title. * @param int $maxResults Maximum number of SIC codes to return. Must be between 1 and 10. Defaults to 5. * @param int $minResults Minimum number of SIC codes to return. Must be at least 1. Defaults to 1. + * @param list $tags Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-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 Type|value-of $type Which SIC dataset to classify against. `original_sic` uses the 1987 Standard Industrial Classification system; `latest_sec` uses the current SIC list as published by the SEC. Defaults to `original_sic`. * @param RequestOpts|null $requestOptions @@ -50,6 +53,7 @@ public function retrieveSic( string $input, int $maxResults = 5, int $minResults = 1, + ?array $tags = null, ?int $timeoutMs = null, Type|string $type = 'original_sic', RequestOptions|array|null $requestOptions = null, diff --git a/src/ServiceContracts/MonitorsContract.php b/src/ServiceContracts/MonitorsContract.php index d18f9e9..0d657e6 100644 --- a/src/ServiceContracts/MonitorsContract.php +++ b/src/ServiceContracts/MonitorsContract.php @@ -108,14 +108,16 @@ public function update( /** * @api * - * @param ChangeDetectionType|value-of $changeDetectionType + * @param ChangeDetectionType|value-of $changeDetectionType filter by change detection type + * @param string $cursor opaque pagination cursor from a previous response + * @param int $limit Maximum number of items to return per page (1-100). Defaults to 25. * @param string $q free-text search term, matched against the fields named in `search_by` - * @param list> $searchBy Comma-separated fields to search with `q`. Defaults to all of them. Note `instructions` only exists on extract monitors. + * @param list>|null $searchBy Comma-separated fields to search with `q`. Defaults to all of them. Note `instructions` only exists on extract monitors. * @param SearchType|value-of $searchType `prefix` for as-you-type prefix matching (default), `exact` for full-token matching - * @param \ContextDev\Monitors\MonitorListParams\Status|value-of<\ContextDev\Monitors\MonitorListParams\Status> $status Monitor lifecycle status. `failed` means the most recent run failed (see the monitor's `last_error`); failed monitors keep running on schedule and flip back to `active` on the next successful run. Monitors are auto-`paused` after repeated consecutive failures or insufficient-credit skips; resume by PATCHing status to `active`. + * @param \ContextDev\Monitors\MonitorListParams\Status|value-of<\ContextDev\Monitors\MonitorListParams\Status> $status filter monitors by lifecycle status * @param string $tag filter to items that have this tag - * @param list $tags comma-separated list of tags to filter by (matches monitors having any of them) - * @param TargetType|value-of $targetType + * @param list|null $tags comma-separated list of tags to filter by (matches monitors having any of them) + * @param TargetType|value-of $targetType filter by target type * @param RequestOpts|null $requestOptions * * @throws APIException @@ -123,10 +125,10 @@ public function update( public function list( ChangeDetectionType|string|null $changeDetectionType = null, ?string $cursor = null, - int $limit = 25, + ?int $limit = null, ?string $q = null, ?array $searchBy = null, - SearchType|string $searchType = 'prefix', + SearchType|string|null $searchType = null, \ContextDev\Monitors\MonitorListParams\Status|string|null $status = null, ?string $tag = null, ?array $tags = null, @@ -149,9 +151,14 @@ public function delete( /** * @api * - * @param \ContextDev\Monitors\MonitorListAccountChangesParams\ChangeDetectionType|value-of<\ContextDev\Monitors\MonitorListAccountChangesParams\ChangeDetectionType> $changeDetectionType + * @param \ContextDev\Monitors\MonitorListAccountChangesParams\ChangeDetectionType|value-of<\ContextDev\Monitors\MonitorListAccountChangesParams\ChangeDetectionType> $changeDetectionType filter by change detection type + * @param string $cursor opaque pagination cursor from a previous response + * @param int $limit Maximum number of items to return per page (1-100). Defaults to 25. + * @param string $monitorID filter changes to a single monitor + * @param \DateTimeInterface $since only include items at or after this ISO 8601 timestamp * @param string $tag filter to items that have this tag - * @param \ContextDev\Monitors\MonitorListAccountChangesParams\TargetType|value-of<\ContextDev\Monitors\MonitorListAccountChangesParams\TargetType> $targetType + * @param \ContextDev\Monitors\MonitorListAccountChangesParams\TargetType|value-of<\ContextDev\Monitors\MonitorListAccountChangesParams\TargetType> $targetType filter by target type + * @param \DateTimeInterface $until only include items before this ISO 8601 timestamp * @param RequestOpts|null $requestOptions * * @throws APIException @@ -159,7 +166,7 @@ public function delete( public function listAccountChanges( \ContextDev\Monitors\MonitorListAccountChangesParams\ChangeDetectionType|string|null $changeDetectionType = null, ?string $cursor = null, - int $limit = 25, + ?int $limit = null, ?string $monitorID = null, ?\DateTimeInterface $since = null, ?string $tag = null, @@ -171,14 +178,16 @@ public function listAccountChanges( /** * @api * - * @param \ContextDev\Monitors\MonitorListAccountRunsParams\Status|value-of<\ContextDev\Monitors\MonitorListAccountRunsParams\Status> $status Lifecycle status of a run. `skipped` runs never executed — see `skip_reason` (insufficient credits, monitor paused, or superseded by a concurrent run). + * @param string $cursor opaque pagination cursor from a previous response + * @param int $limit Maximum number of items to return per page (1-100). Defaults to 25. + * @param \ContextDev\Monitors\MonitorListAccountRunsParams\Status|value-of<\ContextDev\Monitors\MonitorListAccountRunsParams\Status> $status filter runs by lifecycle status * @param RequestOpts|null $requestOptions * * @throws APIException */ public function listAccountRuns( ?string $cursor = null, - int $limit = 25, + ?int $limit = null, \ContextDev\Monitors\MonitorListAccountRunsParams\Status|string|null $status = null, RequestOptions|array|null $requestOptions = null, ): MonitorListAccountRunsResponse; @@ -186,7 +195,11 @@ public function listAccountRuns( /** * @api * + * @param string $cursor opaque pagination cursor from a previous response + * @param int $limit Maximum number of items to return per page (1-100). Defaults to 25. + * @param \DateTimeInterface $since only include items at or after this ISO 8601 timestamp * @param string $tag filter to items that have this tag + * @param \DateTimeInterface $until only include items before this ISO 8601 timestamp * @param RequestOpts|null $requestOptions * * @throws APIException @@ -194,7 +207,7 @@ public function listAccountRuns( public function listChanges( string $monitorID, ?string $cursor = null, - int $limit = 25, + ?int $limit = null, ?\DateTimeInterface $since = null, ?string $tag = null, ?\DateTimeInterface $until = null, @@ -204,7 +217,9 @@ public function listChanges( /** * @api * - * @param \ContextDev\Monitors\MonitorListRunsParams\Status|value-of<\ContextDev\Monitors\MonitorListRunsParams\Status> $status Lifecycle status of a run. `skipped` runs never executed — see `skip_reason` (insufficient credits, monitor paused, or superseded by a concurrent run). + * @param string $cursor opaque pagination cursor from a previous response + * @param int $limit Maximum number of items to return per page (1-100). Defaults to 25. + * @param \ContextDev\Monitors\MonitorListRunsParams\Status|value-of<\ContextDev\Monitors\MonitorListRunsParams\Status> $status filter runs by lifecycle status * @param RequestOpts|null $requestOptions * * @throws APIException @@ -212,7 +227,7 @@ public function listChanges( public function listRuns( string $monitorID, ?string $cursor = null, - int $limit = 25, + ?int $limit = null, \ContextDev\Monitors\MonitorListRunsParams\Status|string|null $status = null, RequestOptions|array|null $requestOptions = null, ): MonitorListRunsResponse; diff --git a/src/ServiceContracts/ParseContract.php b/src/ServiceContracts/ParseContract.php index e6ca67b..baec6c1 100644 --- a/src/ServiceContracts/ParseContract.php +++ b/src/ServiceContracts/ParseContract.php @@ -7,12 +7,18 @@ use ContextDev\Core\Exceptions\APIException; use ContextDev\Core\FileParam; use ContextDev\Parse\ParseHandleParams\Extension; +use ContextDev\Parse\ParseHandleParams\IncludeImages\UnionMember1; use ContextDev\Parse\ParseHandleParams\Pdf; use ContextDev\Parse\ParseHandleResponse; use ContextDev\RequestOptions; /** + * @phpstan-import-type IncludeImagesShape from \ContextDev\Parse\ParseHandleParams\IncludeImages + * @phpstan-import-type IncludeLinksShape from \ContextDev\Parse\ParseHandleParams\IncludeLinks + * @phpstan-import-type OcrShape from \ContextDev\Parse\ParseHandleParams\Ocr * @phpstan-import-type PdfShape from \ContextDev\Parse\ParseHandleParams\Pdf + * @phpstan-import-type ShortenBase64ImagesShape from \ContextDev\Parse\ParseHandleParams\ShortenBase64Images + * @phpstan-import-type UseMainContentOnlyShape from \ContextDev\Parse\ParseHandleParams\UseMainContentOnly * @phpstan-import-type RequestOpts from \ContextDev\RequestOptions */ interface ParseContract @@ -21,26 +27,30 @@ interface ParseContract * @api * * @param string|FileParam $body Body param - * @param Extension|value-of $extension Query param: Optional file extension hint. Case-insensitive; a leading dot is accepted (e.g. ".pdf"). - * @param bool $includeImages Query param: Include image references in Markdown output - * @param bool $includeLinks Query param: Preserve hyperlinks in Markdown output - * @param bool $ocr Query param: Gates all OCR. When true, PDFs get embedded-image OCR (recognized text inserted at each image's position in page reading order, preserving the text layer; pdf.start/pdf.end limit the page range), scanned PDFs with no text layer get full-document OCR, and raster images get their visible text transcribed. When false, no OCR runs: scanned PDFs may yield no content and images return only format/dimension metadata. Calls where OCR actually runs cost 5 credits instead of 1. - * @param Pdf|PdfShape $pdf Query param: PDF page-range controls. Use start/end to limit parsing (and OCR when ocr=true) to an inclusive 1-based page range. - * @param bool $shortenBase64Images Query param: Shorten base64-encoded image data in the Markdown output - * @param bool $useMainContentOnly Query param: Extract only the main content from HTML-like inputs + * @param string $client query param: Optional client identifier used for usage attribution + * @param Extension|value-of $extension query param: Optional file extension hint, such as pdf, docx, xlsx, pptx, html, json, csv, md, py, rtf, jpg, png, or txt + * @param IncludeImagesShape $includeImages Query param: Include image references in Markdown output + * @param IncludeLinksShape $includeLinks Query param: Preserve hyperlinks in Markdown output + * @param OcrShape $ocr Query param: When true for PDF inputs, detect and OCR images embedded in the selected pages, inserting recognized text at each image's position in page reading order while preserving the PDF text layer. pdf.start/pdf.end limit the inclusive page range. When false, all OCR is disabled, including the automatic scanned-PDF fallback. + * @param Pdf|PdfShape $pdf Query param: PDF page-range options as a JSON object, e.g. {"start": 2, "end": 5}. + * @param ShortenBase64ImagesShape $shortenBase64Images Query param: Shorten base64-encoded image data in the Markdown output + * @param list $tags Query param: Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters. + * @param UseMainContentOnlyShape $useMainContentOnly Query param: Extract only the main content from HTML-like inputs * @param RequestOpts|null $requestOptions * * @throws APIException */ public function handle( string|FileParam $body, + ?string $client = null, Extension|string|null $extension = null, - bool $includeImages = false, - bool $includeLinks = true, - bool $ocr = false, + bool|UnionMember1|string $includeImages = false, + bool|\ContextDev\Parse\ParseHandleParams\IncludeLinks\UnionMember1|string $includeLinks = true, + bool|\ContextDev\Parse\ParseHandleParams\Ocr\UnionMember1|string $ocr = false, Pdf|array $pdf = (object) [], - bool $shortenBase64Images = true, - bool $useMainContentOnly = false, + bool|\ContextDev\Parse\ParseHandleParams\ShortenBase64Images\UnionMember1|string $shortenBase64Images = true, + ?array $tags = null, + bool|\ContextDev\Parse\ParseHandleParams\UseMainContentOnly\UnionMember1|string $useMainContentOnly = false, RequestOptions|array|null $requestOptions = null, ): ParseHandleResponse; } diff --git a/src/ServiceContracts/UtilityContract.php b/src/ServiceContracts/UtilityContract.php index 64ca1ad..c318199 100644 --- a/src/ServiceContracts/UtilityContract.php +++ b/src/ServiceContracts/UtilityContract.php @@ -22,6 +22,7 @@ interface UtilityContract * * @param IdentifierShape $identifier Identifier of the brand to prefetch. Provide exactly one of domain or email. * @param Type|value-of $type What to prefetch. Currently only 'brand' is supported. + * @param list $tags Optional caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-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 * @@ -30,6 +31,7 @@ interface UtilityContract public function prefetch( UtilityPrefetchDomainIdentifier|array|UtilityPrefetchEmailIdentifier $identifier, Type|string $type, + ?array $tags = null, ?int $timeoutMs = null, RequestOptions|array|null $requestOptions = null, ): UtilityPrefetchResponse; diff --git a/src/ServiceContracts/WebContract.php b/src/ServiceContracts/WebContract.php index 0a6c2e7..4b8beca 100644 --- a/src/ServiceContracts/WebContract.php +++ b/src/ServiceContracts/WebContract.php @@ -14,7 +14,7 @@ use ContextDev\Web\WebExtractStyleguideResponse; use ContextDev\Web\WebScreenshotParams\Country; use ContextDev\Web\WebScreenshotParams\FullScreenshot; -use ContextDev\Web\WebScreenshotParams\HandleCookiePopup; +use ContextDev\Web\WebScreenshotParams\HandleCookiePopup\UnionMember1; use ContextDev\Web\WebScreenshotParams\Page; use ContextDev\Web\WebScreenshotParams\Viewport; use ContextDev\Web\WebScreenshotResponse; @@ -30,12 +30,23 @@ /** * @phpstan-import-type PdfShape from \ContextDev\Web\WebExtractParams\Pdf + * @phpstan-import-type HandleCookiePopupShape from \ContextDev\Web\WebScreenshotParams\HandleCookiePopup * @phpstan-import-type ViewportShape from \ContextDev\Web\WebScreenshotParams\Viewport * @phpstan-import-type MarkdownOptionsShape from \ContextDev\Web\WebSearchParams\MarkdownOptions * @phpstan-import-type PdfShape from \ContextDev\Web\WebWebCrawlMdParams\Pdf as PdfShape1 + * @phpstan-import-type IncludeFramesShape from \ContextDev\Web\WebWebScrapeHTMLParams\IncludeFrames * @phpstan-import-type PdfShape from \ContextDev\Web\WebWebScrapeHTMLParams\Pdf as PdfShape2 + * @phpstan-import-type SettleAnimationsShape from \ContextDev\Web\WebWebScrapeHTMLParams\SettleAnimations + * @phpstan-import-type UseMainContentOnlyShape from \ContextDev\Web\WebWebScrapeHTMLParams\UseMainContentOnly + * @phpstan-import-type DedupeShape from \ContextDev\Web\WebWebScrapeImagesParams\Dedupe * @phpstan-import-type EnrichmentShape from \ContextDev\Web\WebWebScrapeImagesParams\Enrichment + * @phpstan-import-type IncludeFramesShape from \ContextDev\Web\WebWebScrapeMdParams\IncludeFrames as IncludeFramesShape1 + * @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 + * @phpstan-import-type SettleAnimationsShape from \ContextDev\Web\WebWebScrapeMdParams\SettleAnimations as SettleAnimationsShape1 + * @phpstan-import-type ShortenBase64ImagesShape from \ContextDev\Web\WebWebScrapeMdParams\ShortenBase64Images + * @phpstan-import-type UseMainContentOnlyShape from \ContextDev\Web\WebWebScrapeMdParams\UseMainContentOnly as UseMainContentOnlyShape1 * @phpstan-import-type RequestOpts from \ContextDev\RequestOptions */ interface WebContract @@ -54,6 +65,7 @@ interface WebContract * @param int $maxPages Maximum number of pages to analyze for extraction. Hard cap: 50. Defaults to 5. * @param Pdf|PdfShape $pdf * @param int $stopAfterMs Soft time budget for the crawl in milliseconds. Min: 10000 (10s). Max: 110000 (110s). Default: 80000 (80s). + * @param list $tags Optional caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-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 int $waitForMs optional browser wait time in milliseconds after initial page load for each crawled page * @param RequestOpts|null $requestOptions @@ -72,6 +84,7 @@ public function extract( int $maxPages = 5, Pdf|array $pdf = ['shouldParse' => true], int $stopAfterMs = 80000, + ?array $tags = null, ?int $timeoutMs = null, ?int $waitForMs = null, RequestOptions|array|null $requestOptions = null, @@ -82,6 +95,7 @@ public function extract( * * @param string $domain Company domain to analyze, such as `stripe.com`. Full http(s) URLs are accepted and normalized to their domain. * @param int $numCompetitors Exact number of direct competitors to return. Defaults to 5. + * @param list $tags Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-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 * @@ -90,6 +104,7 @@ public function extract( public function extractCompetitors( string $domain, int $numCompetitors = 5, + ?array $tags = null, ?int $timeoutMs = null, RequestOptions|array|null $requestOptions = null, ): WebExtractCompetitorsResponse; @@ -99,7 +114,8 @@ public function extractCompetitors( * * @param string $directURL A specific URL to fetch fonts from directly, bypassing domain resolution (e.g., 'https://example.com/design-system'). When provided, fonts are extracted from this exact URL. You must provide either 'domain' or 'directUrl', but not both. * @param string $domain Domain name to extract fonts 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. + * @param int|null $maxAgeMs Maximum age in milliseconds for cached brand 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. + * @param list $tags Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-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 * @@ -108,7 +124,8 @@ public function extractCompetitors( public function extractFonts( ?string $directURL = null, ?string $domain = null, - int $maxAgeMs = 7776000000, + ?int $maxAgeMs = 7776000000, + ?array $tags = null, ?int $timeoutMs = null, RequestOptions|array|null $requestOptions = null, ): WebExtractFontsResponse; @@ -119,7 +136,8 @@ public function extractFonts( * @param ColorScheme|value-of $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. + * @param int|null $maxAgeMs Maximum age in milliseconds for cached brand 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. + * @param list $tags Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-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 * @@ -129,7 +147,8 @@ public function extractStyleguide( ColorScheme|string|null $colorScheme = null, ?string $directURL = null, ?string $domain = null, - int $maxAgeMs = 7776000000, + ?int $maxAgeMs = 7776000000, + ?array $tags = null, ?int $timeoutMs = null, RequestOptions|array|null $requestOptions = null, ): WebExtractStyleguideResponse; @@ -138,17 +157,18 @@ 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 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 Country|value-of $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 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 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). - * @param HandleCookiePopup|value-of $handleCookiePopup Optional parameter to control cookie/consent popup handling. If 'true', we dismiss cookie banner before capture. If 'false' or not provided, captures the page without that step. - * @param int $maxAgeMs Return a cached screenshot if a prior screenshot for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always capture fresh. + * @param HandleCookiePopupShape $handleCookiePopup Optional parameter to control cookie/consent popup handling. If 'true', we dismiss cookie banner before capture. If 'false' or not provided, captures the page without that step. + * @param int|null $maxAgeMs Return a cached screenshot if a prior screenshot for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always capture fresh. * @param Page|value-of $page Optional parameter to specify which page type to screenshot. If provided, the system will scrape the domain's links and use heuristics to find the most appropriate URL for the specified page type (30 supported languages). If not provided, screenshots the main domain landing page. Only applicable when using 'domain', not 'directUrl'. - * @param int $scrollOffset Optional vertical scroll offset in pixels for capturing a long page in viewport-sized chunks. When provided, the full page is captured once and the returned image is the viewport-sized slice that begins at this Y offset (e.g. request scrollOffset=0, then 1080, then 2160 to walk a 1920x1080 landing page top to bottom). The final slice may be shorter than the viewport height. Takes precedence over fullScreenshot. Max: 100000. + * @param int|null $scrollOffset Optional vertical scroll offset in pixels for capturing a long page in viewport-sized chunks. When provided, the full page is captured once and the returned image is the viewport-sized slice that begins at this Y offset (e.g. request scrollOffset=0, then 1080, then 2160 to walk a 1920x1080 landing page top to bottom). The final slice may be shorter than the viewport height. Takes precedence over fullScreenshot. Max: 100000. + * @param list $tags Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-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 Viewport|ViewportShape $viewport Optional browser viewport dimensions for the screenshot. Defaults to 1920x1080. - * @param int $waitForMs Optional browser wait time in milliseconds after initial page load before taking the screenshot. Min: 0. Max: 30000 (30 seconds). Defaults to 3000 ms when omitted. + * @param int|null $waitForMs Optional browser wait time in milliseconds after initial page load before taking the screenshot. Min: 0. Max: 30000 (30 seconds). Defaults to 3000 ms when omitted. * @param RequestOpts|null $requestOptions * * @throws APIException @@ -159,13 +179,14 @@ public function screenshot( ?string $directURL = null, ?string $domain = null, FullScreenshot|string|null $fullScreenshot = null, - HandleCookiePopup|string $handleCookiePopup = 'false', - int $maxAgeMs = 86400000, + bool|UnionMember1|string $handleCookiePopup = false, + ?int $maxAgeMs = 86400000, Page|string|null $page = null, ?int $scrollOffset = null, + ?array $tags = null, ?int $timeoutMs = null, Viewport|array $viewport = ['width' => 1920, 'height' => 1080], - int $waitForMs = 3000, + ?int $waitForMs = 3000, RequestOptions|array|null $requestOptions = null, ): WebScreenshotResponse; @@ -180,6 +201,7 @@ public function screenshot( * @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 list $tags Optional caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-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 * @@ -194,6 +216,7 @@ public function search( MarkdownOptions|array|null $markdownOptions = null, int $numResults = 10, ?bool $queryFanout = null, + ?array $tags = null, ?int $timeoutMs = null, RequestOptions|array|null $requestOptions = null, ): WebSearchResponse; @@ -216,6 +239,7 @@ public function search( * @param bool $settleAnimations When true, waits briefly for CSS and transition animations to settle before extracting each crawled page. Defaults to false. This adds a bit of latency in exchange for more stable output on animated pages. * @param bool $shortenBase64Images Truncate base64-encoded image data in the Markdown output * @param int $stopAfterMs Soft time budget for the crawl in milliseconds. After each scrape, the crawler checks the elapsed time and, if exceeded, returns the pages collected so far instead of continuing. Min: 10000 (10s). Max: 110000 (110s). Default: 80000 (80s). + * @param list $tags Optional caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-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 string $urlRegex Regex pattern. Only URLs matching this pattern will be followed and scraped. * @param bool $useMainContentOnly Extract only the main content, stripping headers, footers, sidebars, and navigation @@ -242,6 +266,7 @@ public function webCrawlMd( bool $settleAnimations = false, bool $shortenBase64Images = true, int $stopAfterMs = 80000, + ?array $tags = null, ?int $timeoutMs = null, ?string $urlRegex = null, bool $useMainContentOnly = false, @@ -253,17 +278,18 @@ 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 $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 \ContextDev\Web\WebWebScrapeHTMLParams\Country|value-of<\ContextDev\Web\WebWebScrapeHTMLParams\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|null $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 $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 - * @param list $includeSelectors CSS selectors. When provided, only matching subtrees (and their descendants) are kept and everything else is dropped. When omitted, the entire document is kept. Examples: "article.main", "#content", "[role=main]". - * @param int $maxAgeMs Return a cached result if a prior scrape for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh. + * @param IncludeFramesShape $includeFrames when true, iframes are rendered inline into the returned HTML + * @param list|null $includeSelectors CSS selectors. When provided, only matching subtrees (and their descendants) are kept and everything else is dropped. When omitted, the entire document is kept. Examples: "article.main", "#content", "[role=main]". + * @param int|null $maxAgeMs Return a cached result if a prior scrape for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh. * @param \ContextDev\Web\WebWebScrapeHTMLParams\Pdf|PdfShape2 $pdf PDF parsing controls. Use start/end to limit text extraction and embedded-image detection/OCR to an inclusive 1-based page range. - * @param bool $settleAnimations When true, waits briefly for CSS and transition animations to settle before extracting HTML. Defaults to false. This adds a bit of latency in exchange for more stable output on animated pages. + * @param SettleAnimationsShape $settleAnimations When true, waits briefly for CSS and transition animations to settle before extracting HTML. Defaults to false. This adds a bit of latency in exchange for more stable output on animated pages. + * @param list $tags Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-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 bool $useMainContentOnly when true, return only the page's main content in the HTML response, excluding headers, footers, sidebars, and navigation when detectable - * @param int $waitForMs Optional browser wait time in milliseconds after initial page load. Min: 0. Max: 30000 (30 seconds). + * @param UseMainContentOnlyShape $useMainContentOnly when true, return only the page's main content in the HTML response, excluding headers, footers, sidebars, and navigation when detectable + * @param int|null $waitForMs Optional browser wait time in milliseconds after initial page load. Min: 0. Max: 30000 (30 seconds). * @param RequestOpts|null $requestOptions * * @throws APIException @@ -273,15 +299,16 @@ public function webScrapeHTML( \ContextDev\Web\WebWebScrapeHTMLParams\Country|string|null $country = null, ?array $excludeSelectors = null, ?array $headers = null, - bool $includeFrames = false, + bool|\ContextDev\Web\WebWebScrapeHTMLParams\IncludeFrames\UnionMember1|string $includeFrames = false, ?array $includeSelectors = null, - int $maxAgeMs = 86400000, + ?int $maxAgeMs = 86400000, \ContextDev\Web\WebWebScrapeHTMLParams\Pdf|array $pdf = [ 'shouldParse' => true, 'ocr' => false, ], - bool $settleAnimations = false, + bool|\ContextDev\Web\WebWebScrapeHTMLParams\SettleAnimations\UnionMember1|string $settleAnimations = false, + ?array $tags = null, ?int $timeoutMs = null, - bool $useMainContentOnly = false, + bool|\ContextDev\Web\WebWebScrapeHTMLParams\UseMainContentOnly\UnionMember1|string $useMainContentOnly = false, ?int $waitForMs = null, RequestOptions|array|null $requestOptions = null, ): WebWebScrapeHTMLResponse; @@ -290,22 +317,24 @@ public function webScrapeHTML( * @api * * @param string $url Page URL to inspect. Must include http:// or https://. - * @param bool $dedupe When true, visually duplicate images are removed: every image is loaded and perceptually hashed, and only the highest-resolution copy of each duplicate group is kept. Images that cannot be downloaded or hashed are kept. Default: false. - * @param Enrichment|EnrichmentShape $enrichment optional per-image processing, sent as deep-object query params such as enrichment[resolution]=true + * @param DedupeShape $dedupe When true, visually duplicate images are removed: every image is loaded and perceptually hashed, and only the highest-resolution copy of each duplicate group is kept. Images that cannot be downloaded or hashed are kept. Default: false. + * @param Enrichment|EnrichmentShape|null $enrichment optional per-image processing, sent as deep-object query params such as enrichment[resolution]=true * @param array $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 int $maxAgeMs Reuse a cached result this many milliseconds old or newer. Default: 86400000 (1 day). Set to 0 to bypass cache. Maximum: 2592000000 (30 days). + * @param int|null $maxAgeMs Reuse a cached result this many milliseconds old or newer. Default: 86400000 (1 day). Set to 0 to bypass cache. Maximum: 2592000000 (30 days). + * @param list $tags Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-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 int $waitForMs Optional browser wait time in milliseconds after initial page load before collecting images. Min: 0. Max: 30000 (30 seconds). + * @param int|null $waitForMs Optional browser wait time in milliseconds after initial page load before collecting images. Min: 0. Max: 30000 (30 seconds). * @param RequestOpts|null $requestOptions * * @throws APIException */ public function webScrapeImages( string $url, - bool $dedupe = false, + bool|\ContextDev\Web\WebWebScrapeImagesParams\Dedupe\UnionMember1|string $dedupe = false, Enrichment|array|null $enrichment = null, ?array $headers = null, - int $maxAgeMs = 86400000, + ?int $maxAgeMs = 86400000, + ?array $tags = null, ?int $timeoutMs = null, ?int $waitForMs = null, RequestOptions|array|null $requestOptions = null, @@ -315,20 +344,21 @@ 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 $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 \ContextDev\Web\WebWebScrapeMdParams\Country|value-of<\ContextDev\Web\WebWebScrapeMdParams\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|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 $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 - * @param bool $includeImages Include image references in Markdown output - * @param bool $includeLinks Preserve hyperlinks in Markdown output - * @param list $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]". - * @param int $maxAgeMs Return a cached result if a prior scrape for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh. + * @param IncludeFramesShape1 $includeFrames when true, the contents of iframes are rendered to Markdown + * @param IncludeImagesShape $includeImages Include image references in Markdown output + * @param IncludeLinksShape $includeLinks Preserve hyperlinks in Markdown output + * @param list|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]". + * @param int|null $maxAgeMs Return a cached result if a prior scrape for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh. * @param \ContextDev\Web\WebWebScrapeMdParams\Pdf|PdfShape3 $pdf PDF parsing controls. Use start/end to limit text extraction and embedded-image detection/OCR to an inclusive 1-based page range. - * @param bool $settleAnimations When true, waits briefly for CSS and transition animations to settle before converting to Markdown. Defaults to false. This adds a bit of latency in exchange for more stable output on animated pages. - * @param bool $shortenBase64Images Shorten base64-encoded image data in the Markdown output + * @param SettleAnimationsShape1 $settleAnimations When true, waits briefly for CSS and transition animations to settle before converting to Markdown. Defaults to false. This adds a bit of latency in exchange for more stable output on animated pages. + * @param ShortenBase64ImagesShape $shortenBase64Images Shorten base64-encoded image data in the Markdown output + * @param list $tags Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-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 bool $useMainContentOnly Extract only the main content of the page, excluding headers, footers, sidebars, and navigation - * @param int $waitForMs Optional browser wait time in milliseconds after initial page load before converting the page to Markdown. Min: 0. Max: 30000 (30 seconds). + * @param UseMainContentOnlyShape1 $useMainContentOnly Extract only the main content of the page, excluding headers, footers, sidebars, and navigation + * @param int|null $waitForMs Optional browser wait time in milliseconds after initial page load before converting the page to Markdown. Min: 0. Max: 30000 (30 seconds). * @param RequestOpts|null $requestOptions * * @throws APIException @@ -338,18 +368,19 @@ public function webScrapeMd( \ContextDev\Web\WebWebScrapeMdParams\Country|string|null $country = null, ?array $excludeSelectors = null, ?array $headers = null, - bool $includeFrames = false, - bool $includeImages = false, - bool $includeLinks = true, + bool|\ContextDev\Web\WebWebScrapeMdParams\IncludeFrames\UnionMember1|string $includeFrames = false, + bool|\ContextDev\Web\WebWebScrapeMdParams\IncludeImages\UnionMember1|string $includeImages = false, + bool|\ContextDev\Web\WebWebScrapeMdParams\IncludeLinks\UnionMember1|string $includeLinks = true, ?array $includeSelectors = null, - int $maxAgeMs = 86400000, + ?int $maxAgeMs = 86400000, \ContextDev\Web\WebWebScrapeMdParams\Pdf|array $pdf = [ 'shouldParse' => true, 'ocr' => false, ], - bool $settleAnimations = false, - bool $shortenBase64Images = true, + bool|\ContextDev\Web\WebWebScrapeMdParams\SettleAnimations\UnionMember1|string $settleAnimations = false, + bool|\ContextDev\Web\WebWebScrapeMdParams\ShortenBase64Images\UnionMember1|string $shortenBase64Images = true, + ?array $tags = null, ?int $timeoutMs = null, - bool $useMainContentOnly = false, + bool|\ContextDev\Web\WebWebScrapeMdParams\UseMainContentOnly\UnionMember1|string $useMainContentOnly = false, ?int $waitForMs = null, RequestOptions|array|null $requestOptions = null, ): WebWebScrapeMdResponse; @@ -360,6 +391,8 @@ public function webScrapeMd( * @param string $domain Domain to build a sitemap for * @param array $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 int $maxLinks Maximum number of links to return from the sitemap crawl. Defaults to 10,000. Minimum is 1, maximum is 100,000. + * @param string $sitemapURL Optional explicit sitemap URL. When provided, exactly this sitemap is crawled instead of discovering the domain's sitemaps. + * @param list $tags Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-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 string $urlRegex Optional RE2-compatible regex pattern. Only URLs matching this pattern are returned and counted against maxLinks. * @param RequestOpts|null $requestOptions @@ -370,6 +403,8 @@ public function webScrapeSitemap( string $domain, ?array $headers = null, int $maxLinks = 10000, + ?string $sitemapURL = null, + ?array $tags = null, ?int $timeoutMs = null, ?string $urlRegex = null, RequestOptions|array|null $requestOptions = null, diff --git a/src/Services/AIRawService.php b/src/Services/AIRawService.php index cb6349e..57b7f74 100644 --- a/src/Services/AIRawService.php +++ b/src/Services/AIRawService.php @@ -31,7 +31,7 @@ public function __construct(private Client $client) {} * Given a single URL, determines if it is a product page and extracts the product information. * * @param array{ - * url: string, maxAgeMs?: int, timeoutMs?: int + * url: string, maxAgeMs?: int, tags?: list, timeoutMs?: int * }|AIExtractProductParams $params * @param RequestOpts|null $requestOptions * @@ -67,6 +67,7 @@ public function extractProduct( * domain: string, * maxAgeMs?: int, * maxProducts?: int, + * tags?: list, * timeoutMs?: int, * directURL: string, * }|AIExtractProductsParams $params diff --git a/src/Services/AIService.php b/src/Services/AIService.php index 62949ac..ec959d4 100644 --- a/src/Services/AIService.php +++ b/src/Services/AIService.php @@ -37,6 +37,7 @@ public function __construct(private Client $client) * * @param string $url the product page URL to extract product data from * @param int $maxAgeMs Return a cached result if a prior scrape for the same parameters exists and is younger than this many milliseconds. Defaults to 7 days (604800000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh. + * @param list $tags Optional caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-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 * @@ -45,11 +46,17 @@ public function __construct(private Client $client) public function extractProduct( string $url, int $maxAgeMs = 604800000, + ?array $tags = null, ?int $timeoutMs = null, RequestOptions|array|null $requestOptions = null, ): AIExtractProductResponse { $params = Util::removeNulls( - ['url' => $url, 'maxAgeMs' => $maxAgeMs, 'timeoutMs' => $timeoutMs] + [ + 'url' => $url, + 'maxAgeMs' => $maxAgeMs, + 'tags' => $tags, + 'timeoutMs' => $timeoutMs, + ], ); // @phpstan-ignore-next-line argument.type @@ -67,6 +74,7 @@ public function extractProduct( * @param string $directURL a specific URL to use directly as the starting point for extraction without domain resolution * @param int $maxAgeMs Return a cached result if a prior scrape for the same parameters exists and is younger than this many milliseconds. Defaults to 7 days (604800000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh. * @param int $maxProducts maximum number of products to extract + * @param list $tags Optional caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-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 * @@ -77,6 +85,7 @@ public function extractProducts( string $directURL, int $maxAgeMs = 604800000, ?int $maxProducts = null, + ?array $tags = null, ?int $timeoutMs = null, RequestOptions|array|null $requestOptions = null, ): AIExtractProductsResponse { @@ -85,6 +94,7 @@ public function extractProducts( 'domain' => $domain, 'maxAgeMs' => $maxAgeMs, 'maxProducts' => $maxProducts, + 'tags' => $tags, 'timeoutMs' => $timeoutMs, 'directURL' => $directURL, ], diff --git a/src/Services/BrandRawService.php b/src/Services/BrandRawService.php index b0f6c26..7796a7d 100644 --- a/src/Services/BrandRawService.php +++ b/src/Services/BrandRawService.php @@ -10,6 +10,7 @@ use ContextDev\Brand\BrandRetrieveParams\ForceLanguage; use ContextDev\Brand\BrandRetrieveParams\Type; use ContextDev\Brand\BrandRetrieveSimplifiedParams; +use ContextDev\Brand\BrandRetrieveSimplifiedParams\Theme; use ContextDev\Client; use ContextDev\Core\Contracts\BaseResponse; use ContextDev\Core\Exceptions\APIException; @@ -18,6 +19,8 @@ use ContextDev\ServiceContracts\BrandRawContract; /** + * @phpstan-import-type MccShape from \ContextDev\Brand\BrandRetrieveParams\Mcc + * @phpstan-import-type PhoneShape from \ContextDev\Brand\BrandRetrieveParams\Phone * @phpstan-import-type RequestOpts from \ContextDev\RequestOptions */ final class BrandRawService implements BrandRawContract @@ -39,6 +42,7 @@ public function __construct(private Client $client) {} * forceLanguage?: value-of, * maxAgeMs?: int, * maxSpeed?: bool, + * tags?: list, * timeoutMs?: int, * name: string, * countryGl?: string, @@ -49,8 +53,8 @@ public function __construct(private Client $client) {} * transactionInfo: string, * city?: string, * highConfidenceOnly?: bool, - * mcc?: int, - * phone?: float, + * mcc?: MccShape, + * phone?: PhoneShape, * }|BrandRetrieveParams $params * @param RequestOpts|null $requestOptions * @@ -83,7 +87,11 @@ public function retrieve( * Returns a simplified version of brand data containing only essential information: domain, title, colors, logos, and backdrops. Optimized for faster responses and reduced data transfer. * * @param array{ - * domain: string, maxAgeMs?: int, timeoutMs?: int + * domain: string, + * maxAgeMs?: int|null, + * tags?: list, + * theme?: Theme|value-of, + * timeoutMs?: int, * }|BrandRetrieveSimplifiedParams $params * @param RequestOpts|null $requestOptions * diff --git a/src/Services/BrandService.php b/src/Services/BrandService.php index 63e08ab..96210d0 100644 --- a/src/Services/BrandService.php +++ b/src/Services/BrandService.php @@ -8,6 +8,7 @@ use ContextDev\Brand\BrandGetSimplifiedResponse; use ContextDev\Brand\BrandRetrieveParams\ForceLanguage; use ContextDev\Brand\BrandRetrieveParams\Type; +use ContextDev\Brand\BrandRetrieveSimplifiedParams\Theme; use ContextDev\Client; use ContextDev\Core\Exceptions\APIException; use ContextDev\Core\Util; @@ -15,6 +16,8 @@ use ContextDev\ServiceContracts\BrandContract; /** + * @phpstan-import-type MccShape from \ContextDev\Brand\BrandRetrieveParams\Mcc + * @phpstan-import-type PhoneShape from \ContextDev\Brand\BrandRetrieveParams\Phone * @phpstan-import-type RequestOpts from \ContextDev\RequestOptions */ final class BrandService implements BrandContract @@ -44,16 +47,17 @@ public function __construct(private Client $client) * @param string $ticker Stock ticker symbol to retrieve brand data for (e.g., 'AAPL'). * @param string $directURL Full http(s) URL to fetch brand data from (e.g., 'https://stripe.com/enterprise'). Only this URL is fetched — not the entire internet. * @param string $transactionInfo transaction information to identify the brand - * @param ForceLanguage|value-of $forceLanguage + * @param ForceLanguage|value-of|null $forceLanguage * @param int $maxAgeMs Maximum age in milliseconds for cached brand 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. * @param bool $maxSpeed Optional parameter to optimize the API call for maximum speed. When set to true, the API will skip time-consuming operations for faster response at the cost of less comprehensive data. + * @param list $tags Optional caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-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 string $countryGl optional country code hint (GL parameter) to specify the country when identifying a transaction * @param string $tickerExchange Optional stock exchange for the ticker. Defaults to NASDAQ if not specified. * @param string $city optional city name to prioritize when searching for the brand * @param bool $highConfidenceOnly when set to true, the API performs additional verification to ensure the identified brand matches the transaction with high confidence - * @param int $mcc optional Merchant Category Code (MCC) to help identify the business category or industry - * @param float $phone optional phone number from the transaction to help verify brand match + * @param MccShape $mcc optional Merchant Category Code (MCC) to help identify the business category or industry + * @param PhoneShape $phone optional phone number from the transaction to help verify brand match * @param RequestOpts|null $requestOptions * * @throws APIException @@ -69,13 +73,14 @@ public function retrieve( ForceLanguage|string|null $forceLanguage = null, ?int $maxAgeMs = null, ?bool $maxSpeed = null, + ?array $tags = null, ?int $timeoutMs = null, ?string $countryGl = null, ?string $tickerExchange = null, ?string $city = null, ?bool $highConfidenceOnly = null, - ?int $mcc = null, - ?float $phone = null, + string|float|null $mcc = null, + string|float|null $phone = null, RequestOptions|array|null $requestOptions = null, ): BrandGetResponse { $params = Util::removeNulls( @@ -85,6 +90,7 @@ public function retrieve( 'forceLanguage' => $forceLanguage, 'maxAgeMs' => $maxAgeMs, 'maxSpeed' => $maxSpeed, + 'tags' => $tags, 'timeoutMs' => $timeoutMs, 'name' => $name, 'countryGl' => $countryGl, @@ -112,7 +118,9 @@ public function retrieve( * Returns a simplified version of brand data containing only essential information: domain, title, colors, logos, and backdrops. Optimized for faster responses and reduced data transfer. * * @param string $domain Domain name to retrieve simplified brand data for - * @param int $maxAgeMs Maximum age in milliseconds for cached brand 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. + * @param int|null $maxAgeMs Maximum age in milliseconds for cached brand 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. + * @param list $tags Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters. + * @param Theme|value-of $theme optional theme preference used when selecting brand assets * @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 * @@ -120,12 +128,20 @@ public function retrieve( */ public function retrieveSimplified( string $domain, - int $maxAgeMs = 7776000000, + ?int $maxAgeMs = 7776000000, + ?array $tags = null, + Theme|string|null $theme = null, ?int $timeoutMs = null, RequestOptions|array|null $requestOptions = null, ): BrandGetSimplifiedResponse { $params = Util::removeNulls( - ['domain' => $domain, 'maxAgeMs' => $maxAgeMs, 'timeoutMs' => $timeoutMs] + [ + 'domain' => $domain, + 'maxAgeMs' => $maxAgeMs, + 'tags' => $tags, + 'theme' => $theme, + 'timeoutMs' => $timeoutMs, + ], ); // @phpstan-ignore-next-line argument.type diff --git a/src/Services/IndustryRawService.php b/src/Services/IndustryRawService.php index 9613d74..56ba568 100644 --- a/src/Services/IndustryRawService.php +++ b/src/Services/IndustryRawService.php @@ -33,7 +33,11 @@ public function __construct(private Client $client) {} * Classify any brand into 2022 NAICS industry codes from its domain or name. * * @param array{ - * input: string, maxResults?: int, minResults?: int, timeoutMs?: int + * input: string, + * maxResults?: int, + * minResults?: int, + * tags?: list, + * timeoutMs?: int, * }|IndustryRetrieveNaicsParams $params * @param RequestOpts|null $requestOptions * @@ -69,6 +73,7 @@ public function retrieveNaics( * input: string, * maxResults?: int, * minResults?: int, + * tags?: list, * timeoutMs?: int, * type?: Type|value-of, * }|IndustryRetrieveSicParams $params diff --git a/src/Services/IndustryService.php b/src/Services/IndustryService.php index 47d6a85..3aea60d 100644 --- a/src/Services/IndustryService.php +++ b/src/Services/IndustryService.php @@ -39,6 +39,7 @@ public function __construct(private Client $client) * @param string $input Brand domain or title to retrieve NAICS code for. If a valid domain is provided, it will be used for classification, otherwise, we will search for the brand using the provided title. * @param int $maxResults Maximum number of NAICS codes to return. Must be between 1 and 10. Defaults to 5. * @param int $minResults Minimum number of NAICS codes to return. Must be at least 1. Defaults to 1. + * @param list $tags Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-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 * @@ -48,6 +49,7 @@ public function retrieveNaics( string $input, int $maxResults = 5, int $minResults = 1, + ?array $tags = null, ?int $timeoutMs = null, RequestOptions|array|null $requestOptions = null, ): IndustryGetNaicsResponse { @@ -56,6 +58,7 @@ public function retrieveNaics( 'input' => $input, 'maxResults' => $maxResults, 'minResults' => $minResults, + 'tags' => $tags, 'timeoutMs' => $timeoutMs, ], ); @@ -74,6 +77,7 @@ public function retrieveNaics( * @param string $input Brand domain or title to retrieve SIC code for. If a valid domain is provided, it will be used for classification, otherwise, we will search for the brand using the provided title. * @param int $maxResults Maximum number of SIC codes to return. Must be between 1 and 10. Defaults to 5. * @param int $minResults Minimum number of SIC codes to return. Must be at least 1. Defaults to 1. + * @param list $tags Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-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 Type|value-of $type Which SIC dataset to classify against. `original_sic` uses the 1987 Standard Industrial Classification system; `latest_sec` uses the current SIC list as published by the SEC. Defaults to `original_sic`. * @param RequestOpts|null $requestOptions @@ -84,6 +88,7 @@ public function retrieveSic( string $input, int $maxResults = 5, int $minResults = 1, + ?array $tags = null, ?int $timeoutMs = null, Type|string $type = 'original_sic', RequestOptions|array|null $requestOptions = null, @@ -93,6 +98,7 @@ public function retrieveSic( 'input' => $input, 'maxResults' => $maxResults, 'minResults' => $minResults, + 'tags' => $tags, 'timeoutMs' => $timeoutMs, 'type' => $type, ], diff --git a/src/Services/MonitorsRawService.php b/src/Services/MonitorsRawService.php index 029e994..7251d06 100644 --- a/src/Services/MonitorsRawService.php +++ b/src/Services/MonitorsRawService.php @@ -171,11 +171,11 @@ public function update( * cursor?: string, * limit?: int, * q?: string, - * searchBy?: list>, + * searchBy?: list>|null, * searchType?: SearchType|value-of, * status?: MonitorListParams\Status|value-of, * tag?: string, - * tags?: list, + * tags?: list|null, * targetType?: TargetType|value-of, * }|MonitorListParams $params * @param RequestOpts|null $requestOptions diff --git a/src/Services/MonitorsService.php b/src/Services/MonitorsService.php index d46ad6a..0432335 100644 --- a/src/Services/MonitorsService.php +++ b/src/Services/MonitorsService.php @@ -173,14 +173,16 @@ public function update( * * Lists monitors for the authenticated organization. Supports free-text search (`q` over `search_by` fields, `prefix` or `exact` via `search_type`) plus status/type/tag filters. Results are paginated via the opaque `cursor`. * - * @param ChangeDetectionType|value-of $changeDetectionType + * @param ChangeDetectionType|value-of $changeDetectionType filter by change detection type + * @param string $cursor opaque pagination cursor from a previous response + * @param int $limit Maximum number of items to return per page (1-100). Defaults to 25. * @param string $q free-text search term, matched against the fields named in `search_by` - * @param list> $searchBy Comma-separated fields to search with `q`. Defaults to all of them. Note `instructions` only exists on extract monitors. + * @param list>|null $searchBy Comma-separated fields to search with `q`. Defaults to all of them. Note `instructions` only exists on extract monitors. * @param SearchType|value-of $searchType `prefix` for as-you-type prefix matching (default), `exact` for full-token matching - * @param \ContextDev\Monitors\MonitorListParams\Status|value-of<\ContextDev\Monitors\MonitorListParams\Status> $status Monitor lifecycle status. `failed` means the most recent run failed (see the monitor's `last_error`); failed monitors keep running on schedule and flip back to `active` on the next successful run. Monitors are auto-`paused` after repeated consecutive failures or insufficient-credit skips; resume by PATCHing status to `active`. + * @param \ContextDev\Monitors\MonitorListParams\Status|value-of<\ContextDev\Monitors\MonitorListParams\Status> $status filter monitors by lifecycle status * @param string $tag filter to items that have this tag - * @param list $tags comma-separated list of tags to filter by (matches monitors having any of them) - * @param TargetType|value-of $targetType + * @param list|null $tags comma-separated list of tags to filter by (matches monitors having any of them) + * @param TargetType|value-of $targetType filter by target type * @param RequestOpts|null $requestOptions * * @throws APIException @@ -188,10 +190,10 @@ public function update( public function list( ChangeDetectionType|string|null $changeDetectionType = null, ?string $cursor = null, - int $limit = 25, + ?int $limit = null, ?string $q = null, ?array $searchBy = null, - SearchType|string $searchType = 'prefix', + SearchType|string|null $searchType = null, \ContextDev\Monitors\MonitorListParams\Status|string|null $status = null, ?string $tag = null, ?array $tags = null, @@ -243,9 +245,14 @@ public function delete( * * Returns an account-wide feed of detected changes across monitors. * - * @param \ContextDev\Monitors\MonitorListAccountChangesParams\ChangeDetectionType|value-of<\ContextDev\Monitors\MonitorListAccountChangesParams\ChangeDetectionType> $changeDetectionType + * @param \ContextDev\Monitors\MonitorListAccountChangesParams\ChangeDetectionType|value-of<\ContextDev\Monitors\MonitorListAccountChangesParams\ChangeDetectionType> $changeDetectionType filter by change detection type + * @param string $cursor opaque pagination cursor from a previous response + * @param int $limit Maximum number of items to return per page (1-100). Defaults to 25. + * @param string $monitorID filter changes to a single monitor + * @param \DateTimeInterface $since only include items at or after this ISO 8601 timestamp * @param string $tag filter to items that have this tag - * @param \ContextDev\Monitors\MonitorListAccountChangesParams\TargetType|value-of<\ContextDev\Monitors\MonitorListAccountChangesParams\TargetType> $targetType + * @param \ContextDev\Monitors\MonitorListAccountChangesParams\TargetType|value-of<\ContextDev\Monitors\MonitorListAccountChangesParams\TargetType> $targetType filter by target type + * @param \DateTimeInterface $until only include items before this ISO 8601 timestamp * @param RequestOpts|null $requestOptions * * @throws APIException @@ -253,7 +260,7 @@ public function delete( public function listAccountChanges( \ContextDev\Monitors\MonitorListAccountChangesParams\ChangeDetectionType|string|null $changeDetectionType = null, ?string $cursor = null, - int $limit = 25, + ?int $limit = null, ?string $monitorID = null, ?\DateTimeInterface $since = null, ?string $tag = null, @@ -285,14 +292,16 @@ public function listAccountChanges( * * Returns an account-wide feed of monitor runs across all monitors. * - * @param \ContextDev\Monitors\MonitorListAccountRunsParams\Status|value-of<\ContextDev\Monitors\MonitorListAccountRunsParams\Status> $status Lifecycle status of a run. `skipped` runs never executed — see `skip_reason` (insufficient credits, monitor paused, or superseded by a concurrent run). + * @param string $cursor opaque pagination cursor from a previous response + * @param int $limit Maximum number of items to return per page (1-100). Defaults to 25. + * @param \ContextDev\Monitors\MonitorListAccountRunsParams\Status|value-of<\ContextDev\Monitors\MonitorListAccountRunsParams\Status> $status filter runs by lifecycle status * @param RequestOpts|null $requestOptions * * @throws APIException */ public function listAccountRuns( ?string $cursor = null, - int $limit = 25, + ?int $limit = null, \ContextDev\Monitors\MonitorListAccountRunsParams\Status|string|null $status = null, RequestOptions|array|null $requestOptions = null, ): MonitorListAccountRunsResponse { @@ -311,7 +320,11 @@ public function listAccountRuns( * * List changes for a monitor * + * @param string $cursor opaque pagination cursor from a previous response + * @param int $limit Maximum number of items to return per page (1-100). Defaults to 25. + * @param \DateTimeInterface $since only include items at or after this ISO 8601 timestamp * @param string $tag filter to items that have this tag + * @param \DateTimeInterface $until only include items before this ISO 8601 timestamp * @param RequestOpts|null $requestOptions * * @throws APIException @@ -319,7 +332,7 @@ public function listAccountRuns( public function listChanges( string $monitorID, ?string $cursor = null, - int $limit = 25, + ?int $limit = null, ?\DateTimeInterface $since = null, ?string $tag = null, ?\DateTimeInterface $until = null, @@ -346,7 +359,9 @@ public function listChanges( * * List monitor runs * - * @param \ContextDev\Monitors\MonitorListRunsParams\Status|value-of<\ContextDev\Monitors\MonitorListRunsParams\Status> $status Lifecycle status of a run. `skipped` runs never executed — see `skip_reason` (insufficient credits, monitor paused, or superseded by a concurrent run). + * @param string $cursor opaque pagination cursor from a previous response + * @param int $limit Maximum number of items to return per page (1-100). Defaults to 25. + * @param \ContextDev\Monitors\MonitorListRunsParams\Status|value-of<\ContextDev\Monitors\MonitorListRunsParams\Status> $status filter runs by lifecycle status * @param RequestOpts|null $requestOptions * * @throws APIException @@ -354,7 +369,7 @@ public function listChanges( public function listRuns( string $monitorID, ?string $cursor = null, - int $limit = 25, + ?int $limit = null, \ContextDev\Monitors\MonitorListRunsParams\Status|string|null $status = null, RequestOptions|array|null $requestOptions = null, ): MonitorListRunsResponse { diff --git a/src/Services/ParseRawService.php b/src/Services/ParseRawService.php index 609c9ac..74ec978 100644 --- a/src/Services/ParseRawService.php +++ b/src/Services/ParseRawService.php @@ -16,7 +16,12 @@ use ContextDev\ServiceContracts\ParseRawContract; /** + * @phpstan-import-type IncludeImagesShape from \ContextDev\Parse\ParseHandleParams\IncludeImages + * @phpstan-import-type IncludeLinksShape from \ContextDev\Parse\ParseHandleParams\IncludeLinks + * @phpstan-import-type OcrShape from \ContextDev\Parse\ParseHandleParams\Ocr * @phpstan-import-type PdfShape from \ContextDev\Parse\ParseHandleParams\Pdf + * @phpstan-import-type ShortenBase64ImagesShape from \ContextDev\Parse\ParseHandleParams\ShortenBase64Images + * @phpstan-import-type UseMainContentOnlyShape from \ContextDev\Parse\ParseHandleParams\UseMainContentOnly * @phpstan-import-type RequestOpts from \ContextDev\RequestOptions */ final class ParseRawService implements ParseRawContract @@ -30,17 +35,19 @@ public function __construct(private Client $client) {} /** * @api * - * Converts raw text, source code, web/data, PDF, Microsoft Office, and image bytes into LLM-usable Markdown. The base request costs 1 credit. When OCR runs (requires ocr=true), the entire call costs 5 credits; ocr=true requests where no OCR ends up running still cost 1 credit. + * Converts raw text, source code, web/data, PDF, Microsoft Office, and image bytes into LLM-usable Markdown. * * @param string|FileParam $body Body param * @param array{ + * client?: string, * extension?: value-of, - * includeImages?: bool, - * includeLinks?: bool, - * ocr?: bool, + * includeImages?: IncludeImagesShape, + * includeLinks?: IncludeLinksShape, + * ocr?: OcrShape, * pdf?: Pdf|PdfShape, - * shortenBase64Images?: bool, - * useMainContentOnly?: bool, + * shortenBase64Images?: ShortenBase64ImagesShape, + * tags?: list, + * useMainContentOnly?: UseMainContentOnlyShape, * }|ParseHandleParams $params * @param RequestOpts|null $requestOptions * diff --git a/src/Services/ParseService.php b/src/Services/ParseService.php index fd44ca1..b2dffe0 100644 --- a/src/Services/ParseService.php +++ b/src/Services/ParseService.php @@ -9,13 +9,19 @@ use ContextDev\Core\FileParam; use ContextDev\Core\Util; use ContextDev\Parse\ParseHandleParams\Extension; +use ContextDev\Parse\ParseHandleParams\IncludeImages\UnionMember1; use ContextDev\Parse\ParseHandleParams\Pdf; use ContextDev\Parse\ParseHandleResponse; use ContextDev\RequestOptions; use ContextDev\ServiceContracts\ParseContract; /** + * @phpstan-import-type IncludeImagesShape from \ContextDev\Parse\ParseHandleParams\IncludeImages + * @phpstan-import-type IncludeLinksShape from \ContextDev\Parse\ParseHandleParams\IncludeLinks + * @phpstan-import-type OcrShape from \ContextDev\Parse\ParseHandleParams\Ocr * @phpstan-import-type PdfShape from \ContextDev\Parse\ParseHandleParams\Pdf + * @phpstan-import-type ShortenBase64ImagesShape from \ContextDev\Parse\ParseHandleParams\ShortenBase64Images + * @phpstan-import-type UseMainContentOnlyShape from \ContextDev\Parse\ParseHandleParams\UseMainContentOnly * @phpstan-import-type RequestOpts from \ContextDev\RequestOptions */ final class ParseService implements ParseContract @@ -36,39 +42,45 @@ public function __construct(private Client $client) /** * @api * - * Converts raw text, source code, web/data, PDF, Microsoft Office, and image bytes into LLM-usable Markdown. The base request costs 1 credit. When OCR runs (requires ocr=true), the entire call costs 5 credits; ocr=true requests where no OCR ends up running still cost 1 credit. + * Converts raw text, source code, web/data, PDF, Microsoft Office, and image bytes into LLM-usable Markdown. * * @param string|FileParam $body Body param - * @param Extension|value-of $extension Query param: Optional file extension hint. Case-insensitive; a leading dot is accepted (e.g. ".pdf"). - * @param bool $includeImages Query param: Include image references in Markdown output - * @param bool $includeLinks Query param: Preserve hyperlinks in Markdown output - * @param bool $ocr Query param: Gates all OCR. When true, PDFs get embedded-image OCR (recognized text inserted at each image's position in page reading order, preserving the text layer; pdf.start/pdf.end limit the page range), scanned PDFs with no text layer get full-document OCR, and raster images get their visible text transcribed. When false, no OCR runs: scanned PDFs may yield no content and images return only format/dimension metadata. Calls where OCR actually runs cost 5 credits instead of 1. - * @param Pdf|PdfShape $pdf Query param: PDF page-range controls. Use start/end to limit parsing (and OCR when ocr=true) to an inclusive 1-based page range. - * @param bool $shortenBase64Images Query param: Shorten base64-encoded image data in the Markdown output - * @param bool $useMainContentOnly Query param: Extract only the main content from HTML-like inputs + * @param string $client query param: Optional client identifier used for usage attribution + * @param Extension|value-of $extension query param: Optional file extension hint, such as pdf, docx, xlsx, pptx, html, json, csv, md, py, rtf, jpg, png, or txt + * @param IncludeImagesShape $includeImages Query param: Include image references in Markdown output + * @param IncludeLinksShape $includeLinks Query param: Preserve hyperlinks in Markdown output + * @param OcrShape $ocr Query param: When true for PDF inputs, detect and OCR images embedded in the selected pages, inserting recognized text at each image's position in page reading order while preserving the PDF text layer. pdf.start/pdf.end limit the inclusive page range. When false, all OCR is disabled, including the automatic scanned-PDF fallback. + * @param Pdf|PdfShape $pdf Query param: PDF page-range options as a JSON object, e.g. {"start": 2, "end": 5}. + * @param ShortenBase64ImagesShape $shortenBase64Images Query param: Shorten base64-encoded image data in the Markdown output + * @param list $tags Query param: Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters. + * @param UseMainContentOnlyShape $useMainContentOnly Query param: Extract only the main content from HTML-like inputs * @param RequestOpts|null $requestOptions * * @throws APIException */ public function handle( string|FileParam $body, + ?string $client = null, Extension|string|null $extension = null, - bool $includeImages = false, - bool $includeLinks = true, - bool $ocr = false, + bool|UnionMember1|string $includeImages = false, + bool|\ContextDev\Parse\ParseHandleParams\IncludeLinks\UnionMember1|string $includeLinks = true, + bool|\ContextDev\Parse\ParseHandleParams\Ocr\UnionMember1|string $ocr = false, Pdf|array $pdf = (object) [], - bool $shortenBase64Images = true, - bool $useMainContentOnly = false, + bool|\ContextDev\Parse\ParseHandleParams\ShortenBase64Images\UnionMember1|string $shortenBase64Images = true, + ?array $tags = null, + bool|\ContextDev\Parse\ParseHandleParams\UseMainContentOnly\UnionMember1|string $useMainContentOnly = false, RequestOptions|array|null $requestOptions = null, ): ParseHandleResponse { $params = Util::removeNulls( [ + 'client' => $client, 'extension' => $extension, 'includeImages' => $includeImages, 'includeLinks' => $includeLinks, 'ocr' => $ocr, 'pdf' => $pdf, 'shortenBase64Images' => $shortenBase64Images, + 'tags' => $tags, 'useMainContentOnly' => $useMainContentOnly, ], ); diff --git a/src/Services/UtilityRawService.php b/src/Services/UtilityRawService.php index 7030cad..1b10d93 100644 --- a/src/Services/UtilityRawService.php +++ b/src/Services/UtilityRawService.php @@ -31,7 +31,10 @@ public function __construct(private Client $client) {} * 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). * * @param array{ - * identifier: IdentifierShape, type: Type|value-of, timeoutMs?: int + * identifier: IdentifierShape, + * type: Type|value-of, + * tags?: list, + * timeoutMs?: int, * }|UtilityPrefetchParams $params * @param RequestOpts|null $requestOptions * diff --git a/src/Services/UtilityService.php b/src/Services/UtilityService.php index 8ea4db9..17e59a6 100644 --- a/src/Services/UtilityService.php +++ b/src/Services/UtilityService.php @@ -40,6 +40,7 @@ public function __construct(private Client $client) * * @param IdentifierShape $identifier Identifier of the brand to prefetch. Provide exactly one of domain or email. * @param Type|value-of $type What to prefetch. Currently only 'brand' is supported. + * @param list $tags Optional caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-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 * @@ -48,11 +49,17 @@ public function __construct(private Client $client) public function prefetch( UtilityPrefetchDomainIdentifier|array|UtilityPrefetchEmailIdentifier $identifier, Type|string $type, + ?array $tags = null, ?int $timeoutMs = null, RequestOptions|array|null $requestOptions = null, ): UtilityPrefetchResponse { $params = Util::removeNulls( - ['identifier' => $identifier, 'type' => $type, 'timeoutMs' => $timeoutMs] + [ + 'identifier' => $identifier, + 'type' => $type, + 'tags' => $tags, + 'timeoutMs' => $timeoutMs, + ], ); // @phpstan-ignore-next-line argument.type diff --git a/src/Services/WebRawService.php b/src/Services/WebRawService.php index a7eec12..a9d005d 100644 --- a/src/Services/WebRawService.php +++ b/src/Services/WebRawService.php @@ -23,7 +23,6 @@ use ContextDev\Web\WebScreenshotParams; use ContextDev\Web\WebScreenshotParams\Country; use ContextDev\Web\WebScreenshotParams\FullScreenshot; -use ContextDev\Web\WebScreenshotParams\HandleCookiePopup; use ContextDev\Web\WebScreenshotParams\Page; use ContextDev\Web\WebScreenshotParams\Viewport; use ContextDev\Web\WebScreenshotResponse; @@ -45,12 +44,23 @@ /** * @phpstan-import-type PdfShape from \ContextDev\Web\WebExtractParams\Pdf + * @phpstan-import-type HandleCookiePopupShape from \ContextDev\Web\WebScreenshotParams\HandleCookiePopup * @phpstan-import-type ViewportShape from \ContextDev\Web\WebScreenshotParams\Viewport * @phpstan-import-type MarkdownOptionsShape from \ContextDev\Web\WebSearchParams\MarkdownOptions * @phpstan-import-type PdfShape from \ContextDev\Web\WebWebCrawlMdParams\Pdf as PdfShape1 + * @phpstan-import-type IncludeFramesShape from \ContextDev\Web\WebWebScrapeHTMLParams\IncludeFrames * @phpstan-import-type PdfShape from \ContextDev\Web\WebWebScrapeHTMLParams\Pdf as PdfShape2 + * @phpstan-import-type SettleAnimationsShape from \ContextDev\Web\WebWebScrapeHTMLParams\SettleAnimations + * @phpstan-import-type UseMainContentOnlyShape from \ContextDev\Web\WebWebScrapeHTMLParams\UseMainContentOnly + * @phpstan-import-type DedupeShape from \ContextDev\Web\WebWebScrapeImagesParams\Dedupe * @phpstan-import-type EnrichmentShape from \ContextDev\Web\WebWebScrapeImagesParams\Enrichment + * @phpstan-import-type IncludeFramesShape from \ContextDev\Web\WebWebScrapeMdParams\IncludeFrames as IncludeFramesShape1 + * @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 + * @phpstan-import-type SettleAnimationsShape from \ContextDev\Web\WebWebScrapeMdParams\SettleAnimations as SettleAnimationsShape1 + * @phpstan-import-type ShortenBase64ImagesShape from \ContextDev\Web\WebWebScrapeMdParams\ShortenBase64Images + * @phpstan-import-type UseMainContentOnlyShape from \ContextDev\Web\WebWebScrapeMdParams\UseMainContentOnly as UseMainContentOnlyShape1 * @phpstan-import-type RequestOpts from \ContextDev\RequestOptions */ final class WebRawService implements WebRawContract @@ -78,6 +88,7 @@ public function __construct(private Client $client) {} * maxPages?: int, * pdf?: Pdf|PdfShape, * stopAfterMs?: int, + * tags?: list, * timeoutMs?: int, * waitForMs?: int, * }|WebExtractParams $params @@ -112,7 +123,7 @@ public function extract( * Analyze a company's landing page and web search evidence to return direct competitors for the same product or market. * * @param array{ - * domain: string, numCompetitors?: int, timeoutMs?: int + * domain: string, numCompetitors?: int, tags?: list, timeoutMs?: int * }|WebExtractCompetitorsParams $params * @param RequestOpts|null $requestOptions * @@ -145,7 +156,11 @@ public function extractCompetitors( * Scrape font information from a website including font families, usage statistics, fallbacks, and element/word counts. * * @param array{ - * directURL?: string, domain?: string, maxAgeMs?: int, timeoutMs?: int + * directURL?: string, + * domain?: string, + * maxAgeMs?: int|null, + * tags?: list, + * timeoutMs?: int, * }|WebExtractFontsParams $params * @param RequestOpts|null $requestOptions * @@ -184,7 +199,8 @@ public function extractFonts( * colorScheme?: ColorScheme|value-of, * directURL?: string, * domain?: string, - * maxAgeMs?: int, + * maxAgeMs?: int|null, + * tags?: list, * timeoutMs?: int, * }|WebExtractStyleguideParams $params * @param RequestOpts|null $requestOptions @@ -226,13 +242,14 @@ public function extractStyleguide( * directURL?: string, * domain?: string, * fullScreenshot?: FullScreenshot|value-of, - * handleCookiePopup?: HandleCookiePopup|value-of, - * maxAgeMs?: int, + * handleCookiePopup?: HandleCookiePopupShape, + * maxAgeMs?: int|null, * page?: Page|value-of, - * scrollOffset?: int, + * scrollOffset?: int|null, + * tags?: list, * timeoutMs?: int, * viewport?: Viewport|ViewportShape, - * waitForMs?: int, + * waitForMs?: int|null, * }|WebScreenshotParams $params * @param RequestOpts|null $requestOptions * @@ -276,6 +293,7 @@ public function screenshot( * markdownOptions?: MarkdownOptions|MarkdownOptionsShape, * numResults?: int, * queryFanout?: bool, + * tags?: list, * timeoutMs?: int, * }|WebSearchParams $params * @param RequestOpts|null $requestOptions @@ -324,6 +342,7 @@ public function search( * settleAnimations?: bool, * shortenBase64Images?: bool, * stopAfterMs?: int, + * tags?: list, * timeoutMs?: int, * urlRegex?: string, * useMainContentOnly?: bool, @@ -362,16 +381,17 @@ public function webCrawlMd( * @param array{ * url: string, * country?: value-of, - * excludeSelectors?: list, + * excludeSelectors?: list|null, * headers?: array, - * includeFrames?: bool, - * includeSelectors?: list, - * maxAgeMs?: int, + * includeFrames?: IncludeFramesShape, + * includeSelectors?: list|null, + * maxAgeMs?: int|null, * pdf?: WebWebScrapeHTMLParams\Pdf|PdfShape2, - * settleAnimations?: bool, + * settleAnimations?: SettleAnimationsShape, + * tags?: list, * timeoutMs?: int, - * useMainContentOnly?: bool, - * waitForMs?: int, + * useMainContentOnly?: UseMainContentOnlyShape, + * waitForMs?: int|null, * }|WebWebScrapeHTMLParams $params * @param RequestOpts|null $requestOptions * @@ -405,12 +425,13 @@ public function webScrapeHTML( * * @param array{ * url: string, - * dedupe?: bool, - * enrichment?: Enrichment|EnrichmentShape, + * dedupe?: DedupeShape, + * enrichment?: Enrichment|EnrichmentShape|null, * headers?: array, - * maxAgeMs?: int, + * maxAgeMs?: int|null, + * tags?: list, * timeoutMs?: int, - * waitForMs?: int, + * waitForMs?: int|null, * }|WebWebScrapeImagesParams $params * @param RequestOpts|null $requestOptions * @@ -458,19 +479,20 @@ public function webScrapeImages( * @param array{ * url: string, * country?: value-of, - * excludeSelectors?: list, + * excludeSelectors?: list|null, * headers?: array, - * includeFrames?: bool, - * includeImages?: bool, - * includeLinks?: bool, - * includeSelectors?: list, - * maxAgeMs?: int, + * includeFrames?: IncludeFramesShape1, + * includeImages?: IncludeImagesShape, + * includeLinks?: IncludeLinksShape, + * includeSelectors?: list|null, + * maxAgeMs?: int|null, * pdf?: WebWebScrapeMdParams\Pdf|PdfShape3, - * settleAnimations?: bool, - * shortenBase64Images?: bool, + * settleAnimations?: SettleAnimationsShape1, + * shortenBase64Images?: ShortenBase64ImagesShape, + * tags?: list, * timeoutMs?: int, - * useMainContentOnly?: bool, - * waitForMs?: int, + * useMainContentOnly?: UseMainContentOnlyShape1, + * waitForMs?: int|null, * }|WebWebScrapeMdParams $params * @param RequestOpts|null $requestOptions * @@ -506,6 +528,8 @@ public function webScrapeMd( * domain: string, * headers?: array, * maxLinks?: int, + * sitemapURL?: string, + * tags?: list, * timeoutMs?: int, * urlRegex?: string, * }|WebWebScrapeSitemapParams $params @@ -528,7 +552,10 @@ public function webScrapeSitemap( return $this->client->request( method: 'get', path: 'web/scrape/sitemap', - query: Util::array_transform_keys($parsed, ['timeoutMs' => 'timeoutMS']), + query: Util::array_transform_keys( + $parsed, + ['sitemapURL' => 'sitemapUrl', 'timeoutMs' => 'timeoutMS'] + ), options: $options, convert: WebWebScrapeSitemapResponse::class, ); diff --git a/src/Services/WebService.php b/src/Services/WebService.php index 4331ee8..129ad40 100644 --- a/src/Services/WebService.php +++ b/src/Services/WebService.php @@ -17,7 +17,7 @@ use ContextDev\Web\WebExtractStyleguideResponse; use ContextDev\Web\WebScreenshotParams\Country; use ContextDev\Web\WebScreenshotParams\FullScreenshot; -use ContextDev\Web\WebScreenshotParams\HandleCookiePopup; +use ContextDev\Web\WebScreenshotParams\HandleCookiePopup\UnionMember1; use ContextDev\Web\WebScreenshotParams\Page; use ContextDev\Web\WebScreenshotParams\Viewport; use ContextDev\Web\WebScreenshotResponse; @@ -33,12 +33,23 @@ /** * @phpstan-import-type PdfShape from \ContextDev\Web\WebExtractParams\Pdf + * @phpstan-import-type HandleCookiePopupShape from \ContextDev\Web\WebScreenshotParams\HandleCookiePopup * @phpstan-import-type ViewportShape from \ContextDev\Web\WebScreenshotParams\Viewport * @phpstan-import-type MarkdownOptionsShape from \ContextDev\Web\WebSearchParams\MarkdownOptions * @phpstan-import-type PdfShape from \ContextDev\Web\WebWebCrawlMdParams\Pdf as PdfShape1 + * @phpstan-import-type IncludeFramesShape from \ContextDev\Web\WebWebScrapeHTMLParams\IncludeFrames * @phpstan-import-type PdfShape from \ContextDev\Web\WebWebScrapeHTMLParams\Pdf as PdfShape2 + * @phpstan-import-type SettleAnimationsShape from \ContextDev\Web\WebWebScrapeHTMLParams\SettleAnimations + * @phpstan-import-type UseMainContentOnlyShape from \ContextDev\Web\WebWebScrapeHTMLParams\UseMainContentOnly + * @phpstan-import-type DedupeShape from \ContextDev\Web\WebWebScrapeImagesParams\Dedupe * @phpstan-import-type EnrichmentShape from \ContextDev\Web\WebWebScrapeImagesParams\Enrichment + * @phpstan-import-type IncludeFramesShape from \ContextDev\Web\WebWebScrapeMdParams\IncludeFrames as IncludeFramesShape1 + * @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 + * @phpstan-import-type SettleAnimationsShape from \ContextDev\Web\WebWebScrapeMdParams\SettleAnimations as SettleAnimationsShape1 + * @phpstan-import-type ShortenBase64ImagesShape from \ContextDev\Web\WebWebScrapeMdParams\ShortenBase64Images + * @phpstan-import-type UseMainContentOnlyShape from \ContextDev\Web\WebWebScrapeMdParams\UseMainContentOnly as UseMainContentOnlyShape1 * @phpstan-import-type RequestOpts from \ContextDev\RequestOptions */ final class WebService implements WebContract @@ -72,6 +83,7 @@ public function __construct(private Client $client) * @param int $maxPages Maximum number of pages to analyze for extraction. Hard cap: 50. Defaults to 5. * @param Pdf|PdfShape $pdf * @param int $stopAfterMs Soft time budget for the crawl in milliseconds. Min: 10000 (10s). Max: 110000 (110s). Default: 80000 (80s). + * @param list $tags Optional caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-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 int $waitForMs optional browser wait time in milliseconds after initial page load for each crawled page * @param RequestOpts|null $requestOptions @@ -90,6 +102,7 @@ public function extract( int $maxPages = 5, Pdf|array $pdf = ['shouldParse' => true], int $stopAfterMs = 80000, + ?array $tags = null, ?int $timeoutMs = null, ?int $waitForMs = null, RequestOptions|array|null $requestOptions = null, @@ -107,6 +120,7 @@ public function extract( 'maxPages' => $maxPages, 'pdf' => $pdf, 'stopAfterMs' => $stopAfterMs, + 'tags' => $tags, 'timeoutMs' => $timeoutMs, 'waitForMs' => $waitForMs, ], @@ -125,6 +139,7 @@ public function extract( * * @param string $domain Company domain to analyze, such as `stripe.com`. Full http(s) URLs are accepted and normalized to their domain. * @param int $numCompetitors Exact number of direct competitors to return. Defaults to 5. + * @param list $tags Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-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 * @@ -133,6 +148,7 @@ public function extract( public function extractCompetitors( string $domain, int $numCompetitors = 5, + ?array $tags = null, ?int $timeoutMs = null, RequestOptions|array|null $requestOptions = null, ): WebExtractCompetitorsResponse { @@ -140,6 +156,7 @@ public function extractCompetitors( [ 'domain' => $domain, 'numCompetitors' => $numCompetitors, + 'tags' => $tags, 'timeoutMs' => $timeoutMs, ], ); @@ -157,7 +174,8 @@ public function extractCompetitors( * * @param string $directURL A specific URL to fetch fonts from directly, bypassing domain resolution (e.g., 'https://example.com/design-system'). When provided, fonts are extracted from this exact URL. You must provide either 'domain' or 'directUrl', but not both. * @param string $domain Domain name to extract fonts 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. + * @param int|null $maxAgeMs Maximum age in milliseconds for cached brand 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. + * @param list $tags Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-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 * @@ -166,7 +184,8 @@ public function extractCompetitors( public function extractFonts( ?string $directURL = null, ?string $domain = null, - int $maxAgeMs = 7776000000, + ?int $maxAgeMs = 7776000000, + ?array $tags = null, ?int $timeoutMs = null, RequestOptions|array|null $requestOptions = null, ): WebExtractFontsResponse { @@ -175,6 +194,7 @@ public function extractFonts( 'directURL' => $directURL, 'domain' => $domain, 'maxAgeMs' => $maxAgeMs, + 'tags' => $tags, 'timeoutMs' => $timeoutMs, ], ); @@ -193,7 +213,8 @@ public function extractFonts( * @param ColorScheme|value-of $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. + * @param int|null $maxAgeMs Maximum age in milliseconds for cached brand 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. + * @param list $tags Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-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 * @@ -203,7 +224,8 @@ public function extractStyleguide( ColorScheme|string|null $colorScheme = null, ?string $directURL = null, ?string $domain = null, - int $maxAgeMs = 7776000000, + ?int $maxAgeMs = 7776000000, + ?array $tags = null, ?int $timeoutMs = null, RequestOptions|array|null $requestOptions = null, ): WebExtractStyleguideResponse { @@ -213,6 +235,7 @@ public function extractStyleguide( 'directURL' => $directURL, 'domain' => $domain, 'maxAgeMs' => $maxAgeMs, + 'tags' => $tags, 'timeoutMs' => $timeoutMs, ], ); @@ -229,17 +252,18 @@ public function extractStyleguide( * Capture a screenshot of a website. * * @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 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 Country|value-of $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 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 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). - * @param HandleCookiePopup|value-of $handleCookiePopup Optional parameter to control cookie/consent popup handling. If 'true', we dismiss cookie banner before capture. If 'false' or not provided, captures the page without that step. - * @param int $maxAgeMs Return a cached screenshot if a prior screenshot for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always capture fresh. + * @param HandleCookiePopupShape $handleCookiePopup Optional parameter to control cookie/consent popup handling. If 'true', we dismiss cookie banner before capture. If 'false' or not provided, captures the page without that step. + * @param int|null $maxAgeMs Return a cached screenshot if a prior screenshot for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always capture fresh. * @param Page|value-of $page Optional parameter to specify which page type to screenshot. If provided, the system will scrape the domain's links and use heuristics to find the most appropriate URL for the specified page type (30 supported languages). If not provided, screenshots the main domain landing page. Only applicable when using 'domain', not 'directUrl'. - * @param int $scrollOffset Optional vertical scroll offset in pixels for capturing a long page in viewport-sized chunks. When provided, the full page is captured once and the returned image is the viewport-sized slice that begins at this Y offset (e.g. request scrollOffset=0, then 1080, then 2160 to walk a 1920x1080 landing page top to bottom). The final slice may be shorter than the viewport height. Takes precedence over fullScreenshot. Max: 100000. + * @param int|null $scrollOffset Optional vertical scroll offset in pixels for capturing a long page in viewport-sized chunks. When provided, the full page is captured once and the returned image is the viewport-sized slice that begins at this Y offset (e.g. request scrollOffset=0, then 1080, then 2160 to walk a 1920x1080 landing page top to bottom). The final slice may be shorter than the viewport height. Takes precedence over fullScreenshot. Max: 100000. + * @param list $tags Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-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 Viewport|ViewportShape $viewport Optional browser viewport dimensions for the screenshot. Defaults to 1920x1080. - * @param int $waitForMs Optional browser wait time in milliseconds after initial page load before taking the screenshot. Min: 0. Max: 30000 (30 seconds). Defaults to 3000 ms when omitted. + * @param int|null $waitForMs Optional browser wait time in milliseconds after initial page load before taking the screenshot. Min: 0. Max: 30000 (30 seconds). Defaults to 3000 ms when omitted. * @param RequestOpts|null $requestOptions * * @throws APIException @@ -250,13 +274,14 @@ public function screenshot( ?string $directURL = null, ?string $domain = null, FullScreenshot|string|null $fullScreenshot = null, - HandleCookiePopup|string $handleCookiePopup = 'false', - int $maxAgeMs = 86400000, + bool|UnionMember1|string $handleCookiePopup = false, + ?int $maxAgeMs = 86400000, Page|string|null $page = null, ?int $scrollOffset = null, + ?array $tags = null, ?int $timeoutMs = null, Viewport|array $viewport = ['width' => 1920, 'height' => 1080], - int $waitForMs = 3000, + ?int $waitForMs = 3000, RequestOptions|array|null $requestOptions = null, ): WebScreenshotResponse { $params = Util::removeNulls( @@ -270,6 +295,7 @@ public function screenshot( 'maxAgeMs' => $maxAgeMs, 'page' => $page, 'scrollOffset' => $scrollOffset, + 'tags' => $tags, 'timeoutMs' => $timeoutMs, 'viewport' => $viewport, 'waitForMs' => $waitForMs, @@ -295,6 +321,7 @@ public function screenshot( * @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 list $tags Optional caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-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 * @@ -309,6 +336,7 @@ public function search( MarkdownOptions|array|null $markdownOptions = null, int $numResults = 10, ?bool $queryFanout = null, + ?array $tags = null, ?int $timeoutMs = null, RequestOptions|array|null $requestOptions = null, ): WebSearchResponse { @@ -322,6 +350,7 @@ public function search( 'markdownOptions' => $markdownOptions, 'numResults' => $numResults, 'queryFanout' => $queryFanout, + 'tags' => $tags, 'timeoutMs' => $timeoutMs, ], ); @@ -352,6 +381,7 @@ public function search( * @param bool $settleAnimations When true, waits briefly for CSS and transition animations to settle before extracting each crawled page. Defaults to false. This adds a bit of latency in exchange for more stable output on animated pages. * @param bool $shortenBase64Images Truncate base64-encoded image data in the Markdown output * @param int $stopAfterMs Soft time budget for the crawl in milliseconds. After each scrape, the crawler checks the elapsed time and, if exceeded, returns the pages collected so far instead of continuing. Min: 10000 (10s). Max: 110000 (110s). Default: 80000 (80s). + * @param list $tags Optional caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-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 string $urlRegex Regex pattern. Only URLs matching this pattern will be followed and scraped. * @param bool $useMainContentOnly Extract only the main content, stripping headers, footers, sidebars, and navigation @@ -378,6 +408,7 @@ public function webCrawlMd( bool $settleAnimations = false, bool $shortenBase64Images = true, int $stopAfterMs = 80000, + ?array $tags = null, ?int $timeoutMs = null, ?string $urlRegex = null, bool $useMainContentOnly = false, @@ -401,6 +432,7 @@ public function webCrawlMd( 'settleAnimations' => $settleAnimations, 'shortenBase64Images' => $shortenBase64Images, 'stopAfterMs' => $stopAfterMs, + 'tags' => $tags, 'timeoutMs' => $timeoutMs, 'urlRegex' => $urlRegex, 'useMainContentOnly' => $useMainContentOnly, @@ -420,17 +452,18 @@ public function webCrawlMd( * Scrapes the given URL and returns the raw HTML content of the page. * * @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 $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 \ContextDev\Web\WebWebScrapeHTMLParams\Country|value-of<\ContextDev\Web\WebWebScrapeHTMLParams\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|null $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 $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 - * @param list $includeSelectors CSS selectors. When provided, only matching subtrees (and their descendants) are kept and everything else is dropped. When omitted, the entire document is kept. Examples: "article.main", "#content", "[role=main]". - * @param int $maxAgeMs Return a cached result if a prior scrape for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh. + * @param IncludeFramesShape $includeFrames when true, iframes are rendered inline into the returned HTML + * @param list|null $includeSelectors CSS selectors. When provided, only matching subtrees (and their descendants) are kept and everything else is dropped. When omitted, the entire document is kept. Examples: "article.main", "#content", "[role=main]". + * @param int|null $maxAgeMs Return a cached result if a prior scrape for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh. * @param \ContextDev\Web\WebWebScrapeHTMLParams\Pdf|PdfShape2 $pdf PDF parsing controls. Use start/end to limit text extraction and embedded-image detection/OCR to an inclusive 1-based page range. - * @param bool $settleAnimations When true, waits briefly for CSS and transition animations to settle before extracting HTML. Defaults to false. This adds a bit of latency in exchange for more stable output on animated pages. + * @param SettleAnimationsShape $settleAnimations When true, waits briefly for CSS and transition animations to settle before extracting HTML. Defaults to false. This adds a bit of latency in exchange for more stable output on animated pages. + * @param list $tags Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-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 bool $useMainContentOnly when true, return only the page's main content in the HTML response, excluding headers, footers, sidebars, and navigation when detectable - * @param int $waitForMs Optional browser wait time in milliseconds after initial page load. Min: 0. Max: 30000 (30 seconds). + * @param UseMainContentOnlyShape $useMainContentOnly when true, return only the page's main content in the HTML response, excluding headers, footers, sidebars, and navigation when detectable + * @param int|null $waitForMs Optional browser wait time in milliseconds after initial page load. Min: 0. Max: 30000 (30 seconds). * @param RequestOpts|null $requestOptions * * @throws APIException @@ -440,15 +473,16 @@ public function webScrapeHTML( \ContextDev\Web\WebWebScrapeHTMLParams\Country|string|null $country = null, ?array $excludeSelectors = null, ?array $headers = null, - bool $includeFrames = false, + bool|\ContextDev\Web\WebWebScrapeHTMLParams\IncludeFrames\UnionMember1|string $includeFrames = false, ?array $includeSelectors = null, - int $maxAgeMs = 86400000, + ?int $maxAgeMs = 86400000, \ContextDev\Web\WebWebScrapeHTMLParams\Pdf|array $pdf = [ 'shouldParse' => true, 'ocr' => false, ], - bool $settleAnimations = false, + bool|\ContextDev\Web\WebWebScrapeHTMLParams\SettleAnimations\UnionMember1|string $settleAnimations = false, + ?array $tags = null, ?int $timeoutMs = null, - bool $useMainContentOnly = false, + bool|\ContextDev\Web\WebWebScrapeHTMLParams\UseMainContentOnly\UnionMember1|string $useMainContentOnly = false, ?int $waitForMs = null, RequestOptions|array|null $requestOptions = null, ): WebWebScrapeHTMLResponse { @@ -463,6 +497,7 @@ public function webScrapeHTML( 'maxAgeMs' => $maxAgeMs, 'pdf' => $pdf, 'settleAnimations' => $settleAnimations, + 'tags' => $tags, 'timeoutMs' => $timeoutMs, 'useMainContentOnly' => $useMainContentOnly, 'waitForMs' => $waitForMs, @@ -481,22 +516,24 @@ public function webScrapeHTML( * Extract image assets from a web page, including standard URLs, inline SVGs, data URIs, responsive image sources, metadata, CSS backgrounds, video posters, and embeds. The base request costs 1 credit. When enrichment is enabled, the entire call costs 5 credits. * * @param string $url Page URL to inspect. Must include http:// or https://. - * @param bool $dedupe When true, visually duplicate images are removed: every image is loaded and perceptually hashed, and only the highest-resolution copy of each duplicate group is kept. Images that cannot be downloaded or hashed are kept. Default: false. - * @param Enrichment|EnrichmentShape $enrichment optional per-image processing, sent as deep-object query params such as enrichment[resolution]=true + * @param DedupeShape $dedupe When true, visually duplicate images are removed: every image is loaded and perceptually hashed, and only the highest-resolution copy of each duplicate group is kept. Images that cannot be downloaded or hashed are kept. Default: false. + * @param Enrichment|EnrichmentShape|null $enrichment optional per-image processing, sent as deep-object query params such as enrichment[resolution]=true * @param array $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 int $maxAgeMs Reuse a cached result this many milliseconds old or newer. Default: 86400000 (1 day). Set to 0 to bypass cache. Maximum: 2592000000 (30 days). + * @param int|null $maxAgeMs Reuse a cached result this many milliseconds old or newer. Default: 86400000 (1 day). Set to 0 to bypass cache. Maximum: 2592000000 (30 days). + * @param list $tags Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-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 int $waitForMs Optional browser wait time in milliseconds after initial page load before collecting images. Min: 0. Max: 30000 (30 seconds). + * @param int|null $waitForMs Optional browser wait time in milliseconds after initial page load before collecting images. Min: 0. Max: 30000 (30 seconds). * @param RequestOpts|null $requestOptions * * @throws APIException */ public function webScrapeImages( string $url, - bool $dedupe = false, + bool|\ContextDev\Web\WebWebScrapeImagesParams\Dedupe\UnionMember1|string $dedupe = false, Enrichment|array|null $enrichment = null, ?array $headers = null, - int $maxAgeMs = 86400000, + ?int $maxAgeMs = 86400000, + ?array $tags = null, ?int $timeoutMs = null, ?int $waitForMs = null, RequestOptions|array|null $requestOptions = null, @@ -508,6 +545,7 @@ public function webScrapeImages( 'enrichment' => $enrichment, 'headers' => $headers, 'maxAgeMs' => $maxAgeMs, + 'tags' => $tags, 'timeoutMs' => $timeoutMs, 'waitForMs' => $waitForMs, ], @@ -538,20 +576,21 @@ public function webScrapeImages( * | 500 | No | Internal error | * * @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 $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 \ContextDev\Web\WebWebScrapeMdParams\Country|value-of<\ContextDev\Web\WebWebScrapeMdParams\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|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 $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 - * @param bool $includeImages Include image references in Markdown output - * @param bool $includeLinks Preserve hyperlinks in Markdown output - * @param list $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]". - * @param int $maxAgeMs Return a cached result if a prior scrape for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh. + * @param IncludeFramesShape1 $includeFrames when true, the contents of iframes are rendered to Markdown + * @param IncludeImagesShape $includeImages Include image references in Markdown output + * @param IncludeLinksShape $includeLinks Preserve hyperlinks in Markdown output + * @param list|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]". + * @param int|null $maxAgeMs Return a cached result if a prior scrape for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh. * @param \ContextDev\Web\WebWebScrapeMdParams\Pdf|PdfShape3 $pdf PDF parsing controls. Use start/end to limit text extraction and embedded-image detection/OCR to an inclusive 1-based page range. - * @param bool $settleAnimations When true, waits briefly for CSS and transition animations to settle before converting to Markdown. Defaults to false. This adds a bit of latency in exchange for more stable output on animated pages. - * @param bool $shortenBase64Images Shorten base64-encoded image data in the Markdown output + * @param SettleAnimationsShape1 $settleAnimations When true, waits briefly for CSS and transition animations to settle before converting to Markdown. Defaults to false. This adds a bit of latency in exchange for more stable output on animated pages. + * @param ShortenBase64ImagesShape $shortenBase64Images Shorten base64-encoded image data in the Markdown output + * @param list $tags Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-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 bool $useMainContentOnly Extract only the main content of the page, excluding headers, footers, sidebars, and navigation - * @param int $waitForMs Optional browser wait time in milliseconds after initial page load before converting the page to Markdown. Min: 0. Max: 30000 (30 seconds). + * @param UseMainContentOnlyShape1 $useMainContentOnly Extract only the main content of the page, excluding headers, footers, sidebars, and navigation + * @param int|null $waitForMs Optional browser wait time in milliseconds after initial page load before converting the page to Markdown. Min: 0. Max: 30000 (30 seconds). * @param RequestOpts|null $requestOptions * * @throws APIException @@ -561,18 +600,19 @@ public function webScrapeMd( \ContextDev\Web\WebWebScrapeMdParams\Country|string|null $country = null, ?array $excludeSelectors = null, ?array $headers = null, - bool $includeFrames = false, - bool $includeImages = false, - bool $includeLinks = true, + bool|\ContextDev\Web\WebWebScrapeMdParams\IncludeFrames\UnionMember1|string $includeFrames = false, + bool|\ContextDev\Web\WebWebScrapeMdParams\IncludeImages\UnionMember1|string $includeImages = false, + bool|\ContextDev\Web\WebWebScrapeMdParams\IncludeLinks\UnionMember1|string $includeLinks = true, ?array $includeSelectors = null, - int $maxAgeMs = 86400000, + ?int $maxAgeMs = 86400000, \ContextDev\Web\WebWebScrapeMdParams\Pdf|array $pdf = [ 'shouldParse' => true, 'ocr' => false, ], - bool $settleAnimations = false, - bool $shortenBase64Images = true, + bool|\ContextDev\Web\WebWebScrapeMdParams\SettleAnimations\UnionMember1|string $settleAnimations = false, + bool|\ContextDev\Web\WebWebScrapeMdParams\ShortenBase64Images\UnionMember1|string $shortenBase64Images = true, + ?array $tags = null, ?int $timeoutMs = null, - bool $useMainContentOnly = false, + bool|\ContextDev\Web\WebWebScrapeMdParams\UseMainContentOnly\UnionMember1|string $useMainContentOnly = false, ?int $waitForMs = null, RequestOptions|array|null $requestOptions = null, ): WebWebScrapeMdResponse { @@ -590,6 +630,7 @@ public function webScrapeMd( 'pdf' => $pdf, 'settleAnimations' => $settleAnimations, 'shortenBase64Images' => $shortenBase64Images, + 'tags' => $tags, 'timeoutMs' => $timeoutMs, 'useMainContentOnly' => $useMainContentOnly, 'waitForMs' => $waitForMs, @@ -610,6 +651,8 @@ public function webScrapeMd( * @param string $domain Domain to build a sitemap for * @param array $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 int $maxLinks Maximum number of links to return from the sitemap crawl. Defaults to 10,000. Minimum is 1, maximum is 100,000. + * @param string $sitemapURL Optional explicit sitemap URL. When provided, exactly this sitemap is crawled instead of discovering the domain's sitemaps. + * @param list $tags Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-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 string $urlRegex Optional RE2-compatible regex pattern. Only URLs matching this pattern are returned and counted against maxLinks. * @param RequestOpts|null $requestOptions @@ -620,6 +663,8 @@ public function webScrapeSitemap( string $domain, ?array $headers = null, int $maxLinks = 10000, + ?string $sitemapURL = null, + ?array $tags = null, ?int $timeoutMs = null, ?string $urlRegex = null, RequestOptions|array|null $requestOptions = null, @@ -629,6 +674,8 @@ public function webScrapeSitemap( 'domain' => $domain, 'headers' => $headers, 'maxLinks' => $maxLinks, + 'sitemapURL' => $sitemapURL, + 'tags' => $tags, 'timeoutMs' => $timeoutMs, 'urlRegex' => $urlRegex, ], diff --git a/src/Utility/UtilityPrefetchParams.php b/src/Utility/UtilityPrefetchParams.php index 0082269..dfdb913 100644 --- a/src/Utility/UtilityPrefetchParams.php +++ b/src/Utility/UtilityPrefetchParams.php @@ -22,7 +22,10 @@ * @phpstan-import-type IdentifierShape from \ContextDev\Utility\UtilityPrefetchParams\Identifier * * @phpstan-type UtilityPrefetchParamsShape = array{ - * identifier: IdentifierShape, type: Type|value-of, timeoutMs?: int|null + * identifier: IdentifierShape, + * type: Type|value-of, + * tags?: list|null, + * timeoutMs?: int|null, * } */ final class UtilityPrefetchParams implements BaseModel @@ -47,6 +50,14 @@ final class UtilityPrefetchParams implements BaseModel #[Required(enum: Type::class)] public string $type; + /** + * Optional caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters. + * + * @var list|null $tags + */ + #[Optional(list: 'string')] + public ?array $tags; + /** * 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). */ @@ -79,10 +90,12 @@ public function __construct() * * @param IdentifierShape $identifier * @param Type|value-of $type + * @param list|null $tags */ public static function with( UtilityPrefetchDomainIdentifier|array|UtilityPrefetchEmailIdentifier $identifier, Type|string $type, + ?array $tags = null, ?int $timeoutMs = null, ): self { $self = new self; @@ -90,6 +103,7 @@ public static function with( $self['identifier'] = $identifier; $self['type'] = $type; + null !== $tags && $self['tags'] = $tags; null !== $timeoutMs && $self['timeoutMs'] = $timeoutMs; return $self; @@ -122,6 +136,19 @@ public function withType(Type|string $type): self return $self; } + /** + * Optional caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters. + * + * @param list $tags + */ + public function withTags(array $tags): self + { + $self = clone $this; + $self['tags'] = $tags; + + return $self; + } + /** * 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). */ diff --git a/src/Version.php b/src/Version.php index 3d8b900..1c11a97 100644 --- a/src/Version.php +++ b/src/Version.php @@ -5,5 +5,5 @@ namespace ContextDev; // x-release-please-start-version -const VERSION = '2.4.0'; +const VERSION = '2.5.0'; // x-release-please-end diff --git a/src/Web/WebExtractCompetitorsParams.php b/src/Web/WebExtractCompetitorsParams.php index fe4f94b..547ed13 100644 --- a/src/Web/WebExtractCompetitorsParams.php +++ b/src/Web/WebExtractCompetitorsParams.php @@ -16,7 +16,10 @@ * @see ContextDev\Services\WebService::extractCompetitors() * * @phpstan-type WebExtractCompetitorsParamsShape = array{ - * domain: string, numCompetitors?: int|null, timeoutMs?: int|null + * domain: string, + * numCompetitors?: int|null, + * tags?: list|null, + * timeoutMs?: int|null, * } */ final class WebExtractCompetitorsParams implements BaseModel @@ -37,6 +40,14 @@ final class WebExtractCompetitorsParams implements BaseModel #[Optional] public ?int $numCompetitors; + /** + * Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters. + * + * @var list|null $tags + */ + #[Optional(list: 'string')] + public ?array $tags; + /** * 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). */ @@ -66,17 +77,21 @@ public function __construct() * Construct an instance from the required parameters. * * You must use named parameters to construct any parameters with a default value. + * + * @param list|null $tags */ public static function with( string $domain, ?int $numCompetitors = null, - ?int $timeoutMs = null + ?array $tags = null, + ?int $timeoutMs = null, ): self { $self = new self; $self['domain'] = $domain; null !== $numCompetitors && $self['numCompetitors'] = $numCompetitors; + null !== $tags && $self['tags'] = $tags; null !== $timeoutMs && $self['timeoutMs'] = $timeoutMs; return $self; @@ -104,6 +119,19 @@ public function withNumCompetitors(int $numCompetitors): self return $self; } + /** + * Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters. + * + * @param list $tags + */ + public function withTags(array $tags): self + { + $self = clone $this; + $self['tags'] = $tags; + + return $self; + } + /** * 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). */ diff --git a/src/Web/WebExtractFontsParams.php b/src/Web/WebExtractFontsParams.php index e8e51d1..ce89edc 100644 --- a/src/Web/WebExtractFontsParams.php +++ b/src/Web/WebExtractFontsParams.php @@ -18,6 +18,7 @@ * directURL?: string|null, * domain?: string|null, * maxAgeMs?: int|null, + * tags?: list|null, * timeoutMs?: int|null, * } */ @@ -40,11 +41,19 @@ final class WebExtractFontsParams implements BaseModel public ?string $domain; /** - * 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. + * Maximum age in milliseconds for cached brand 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. */ - #[Optional] + #[Optional(nullable: true)] public ?int $maxAgeMs; + /** + * Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters. + * + * @var list|null $tags + */ + #[Optional(list: 'string')] + public ?array $tags; + /** * 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). */ @@ -60,11 +69,14 @@ public function __construct() * Construct an instance from the required parameters. * * You must use named parameters to construct any parameters with a default value. + * + * @param list|null $tags */ public static function with( ?string $directURL = null, ?string $domain = null, ?int $maxAgeMs = null, + ?array $tags = null, ?int $timeoutMs = null, ): self { $self = new self; @@ -72,6 +84,7 @@ public static function with( null !== $directURL && $self['directURL'] = $directURL; null !== $domain && $self['domain'] = $domain; null !== $maxAgeMs && $self['maxAgeMs'] = $maxAgeMs; + null !== $tags && $self['tags'] = $tags; null !== $timeoutMs && $self['timeoutMs'] = $timeoutMs; return $self; @@ -100,9 +113,9 @@ public function withDomain(string $domain): self } /** - * 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. + * Maximum age in milliseconds for cached brand 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. */ - public function withMaxAgeMs(int $maxAgeMs): self + public function withMaxAgeMs(?int $maxAgeMs): self { $self = clone $this; $self['maxAgeMs'] = $maxAgeMs; @@ -110,6 +123,19 @@ public function withMaxAgeMs(int $maxAgeMs): self return $self; } + /** + * Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters. + * + * @param list $tags + */ + public function withTags(array $tags): self + { + $self = clone $this; + $self['tags'] = $tags; + + return $self; + } + /** * 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). */ diff --git a/src/Web/WebExtractParams.php b/src/Web/WebExtractParams.php index 66234f5..4791321 100644 --- a/src/Web/WebExtractParams.php +++ b/src/Web/WebExtractParams.php @@ -30,6 +30,7 @@ * maxPages?: int|null, * pdf?: null|Pdf|PdfShape, * stopAfterMs?: int|null, + * tags?: list|null, * timeoutMs?: int|null, * waitForMs?: int|null, * } @@ -105,6 +106,14 @@ final class WebExtractParams implements BaseModel #[Optional] public ?int $stopAfterMs; + /** + * Optional caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters. + * + * @var list|null $tags + */ + #[Optional(list: 'string')] + public ?array $tags; + /** * 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). */ @@ -143,6 +152,7 @@ public function __construct() * * @param array $schema * @param Pdf|PdfShape|null $pdf + * @param list|null $tags */ public static function with( array $schema, @@ -156,6 +166,7 @@ public static function with( ?int $maxPages = null, Pdf|array|null $pdf = null, ?int $stopAfterMs = null, + ?array $tags = null, ?int $timeoutMs = null, ?int $waitForMs = null, ): self { @@ -173,6 +184,7 @@ public static function with( null !== $maxPages && $self['maxPages'] = $maxPages; null !== $pdf && $self['pdf'] = $pdf; null !== $stopAfterMs && $self['stopAfterMs'] = $stopAfterMs; + null !== $tags && $self['tags'] = $tags; null !== $timeoutMs && $self['timeoutMs'] = $timeoutMs; null !== $waitForMs && $self['waitForMs'] = $waitForMs; @@ -302,6 +314,19 @@ public function withStopAfterMs(int $stopAfterMs): self return $self; } + /** + * Optional caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters. + * + * @param list $tags + */ + public function withTags(array $tags): self + { + $self = clone $this; + $self['tags'] = $tags; + + return $self; + } + /** * 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). */ diff --git a/src/Web/WebExtractStyleguideParams.php b/src/Web/WebExtractStyleguideParams.php index a4ba242..af8fd34 100644 --- a/src/Web/WebExtractStyleguideParams.php +++ b/src/Web/WebExtractStyleguideParams.php @@ -20,6 +20,7 @@ * directURL?: string|null, * domain?: string|null, * maxAgeMs?: int|null, + * tags?: list|null, * timeoutMs?: int|null, * } */ @@ -50,11 +51,19 @@ final class WebExtractStyleguideParams implements BaseModel public ?string $domain; /** - * 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. + * Maximum age in milliseconds for cached brand 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. */ - #[Optional] + #[Optional(nullable: true)] public ?int $maxAgeMs; + /** + * Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters. + * + * @var list|null $tags + */ + #[Optional(list: 'string')] + public ?array $tags; + /** * 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). */ @@ -72,12 +81,14 @@ public function __construct() * You must use named parameters to construct any parameters with a default value. * * @param ColorScheme|value-of|null $colorScheme + * @param list|null $tags */ public static function with( ColorScheme|string|null $colorScheme = null, ?string $directURL = null, ?string $domain = null, ?int $maxAgeMs = null, + ?array $tags = null, ?int $timeoutMs = null, ): self { $self = new self; @@ -86,6 +97,7 @@ public static function with( null !== $directURL && $self['directURL'] = $directURL; null !== $domain && $self['domain'] = $domain; null !== $maxAgeMs && $self['maxAgeMs'] = $maxAgeMs; + null !== $tags && $self['tags'] = $tags; null !== $timeoutMs && $self['timeoutMs'] = $timeoutMs; return $self; @@ -127,9 +139,9 @@ public function withDomain(string $domain): self } /** - * 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. + * Maximum age in milliseconds for cached brand 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. */ - public function withMaxAgeMs(int $maxAgeMs): self + public function withMaxAgeMs(?int $maxAgeMs): self { $self = clone $this; $self['maxAgeMs'] = $maxAgeMs; @@ -137,6 +149,19 @@ public function withMaxAgeMs(int $maxAgeMs): self return $self; } + /** + * Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters. + * + * @param list $tags + */ + public function withTags(array $tags): self + { + $self = clone $this; + $self['tags'] = $tags; + + return $self; + } + /** * 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). */ diff --git a/src/Web/WebScreenshotParams.php b/src/Web/WebScreenshotParams.php index ffc9eee..3f818a3 100644 --- a/src/Web/WebScreenshotParams.php +++ b/src/Web/WebScreenshotParams.php @@ -12,6 +12,7 @@ use ContextDev\Web\WebScreenshotParams\Country; use ContextDev\Web\WebScreenshotParams\FullScreenshot; use ContextDev\Web\WebScreenshotParams\HandleCookiePopup; +use ContextDev\Web\WebScreenshotParams\HandleCookiePopup\UnionMember1; use ContextDev\Web\WebScreenshotParams\Page; use ContextDev\Web\WebScreenshotParams\Viewport; @@ -20,6 +21,8 @@ * * @see ContextDev\Services\WebService::screenshot() * + * @phpstan-import-type HandleCookiePopupVariants from \ContextDev\Web\WebScreenshotParams\HandleCookiePopup + * @phpstan-import-type HandleCookiePopupShape from \ContextDev\Web\WebScreenshotParams\HandleCookiePopup * @phpstan-import-type ViewportShape from \ContextDev\Web\WebScreenshotParams\Viewport * * @phpstan-type WebScreenshotParamsShape = array{ @@ -28,10 +31,11 @@ * directURL?: string|null, * domain?: string|null, * fullScreenshot?: null|FullScreenshot|value-of, - * handleCookiePopup?: null|HandleCookiePopup|value-of, + * handleCookiePopup?: HandleCookiePopupShape|null, * maxAgeMs?: int|null, * page?: null|Page|value-of, * scrollOffset?: int|null, + * tags?: list|null, * timeoutMs?: int|null, * viewport?: null|Viewport|ViewportShape, * waitForMs?: int|null, @@ -52,7 +56,7 @@ final class WebScreenshotParams implements BaseModel public ?string $colorScheme; /** - * 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. + * 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. * * @var value-of|null $country */ @@ -82,15 +86,15 @@ final class WebScreenshotParams implements BaseModel /** * Optional parameter to control cookie/consent popup handling. If 'true', we dismiss cookie banner before capture. If 'false' or not provided, captures the page without that step. * - * @var value-of|null $handleCookiePopup + * @var HandleCookiePopupVariants|null $handleCookiePopup */ - #[Optional(enum: HandleCookiePopup::class)] - public ?string $handleCookiePopup; + #[Optional(union: HandleCookiePopup::class)] + public bool|string|null $handleCookiePopup; /** * Return a cached screenshot if a prior screenshot for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always capture fresh. */ - #[Optional] + #[Optional(nullable: true)] public ?int $maxAgeMs; /** @@ -104,9 +108,17 @@ final class WebScreenshotParams implements BaseModel /** * Optional vertical scroll offset in pixels for capturing a long page in viewport-sized chunks. When provided, the full page is captured once and the returned image is the viewport-sized slice that begins at this Y offset (e.g. request scrollOffset=0, then 1080, then 2160 to walk a 1920x1080 landing page top to bottom). The final slice may be shorter than the viewport height. Takes precedence over fullScreenshot. Max: 100000. */ - #[Optional] + #[Optional(nullable: true)] public ?int $scrollOffset; + /** + * Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters. + * + * @var list|null $tags + */ + #[Optional(list: 'string')] + public ?array $tags; + /** * 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). */ @@ -120,9 +132,9 @@ final class WebScreenshotParams implements BaseModel public ?Viewport $viewport; /** - * Optional browser wait time in milliseconds after initial page load before taking the screenshot. Min: 0. Max: 30000 (30 seconds). Defaults to 3000 ms when omitted. + * Optional browser wait time in milliseconds after initial page load before taking the screenshot. Min: 0. Max: 30000 (30 seconds). Defaults to 3000 ms when omitted. */ - #[Optional] + #[Optional(nullable: true)] public ?int $waitForMs; public function __construct() @@ -138,8 +150,9 @@ public function __construct() * @param ColorScheme|value-of|null $colorScheme * @param Country|value-of|null $country * @param FullScreenshot|value-of|null $fullScreenshot - * @param HandleCookiePopup|value-of|null $handleCookiePopup + * @param HandleCookiePopupShape|null $handleCookiePopup * @param Page|value-of|null $page + * @param list|null $tags * @param Viewport|ViewportShape|null $viewport */ public static function with( @@ -148,10 +161,11 @@ public static function with( ?string $directURL = null, ?string $domain = null, FullScreenshot|string|null $fullScreenshot = null, - HandleCookiePopup|string|null $handleCookiePopup = null, + bool|UnionMember1|string|null $handleCookiePopup = null, ?int $maxAgeMs = null, Page|string|null $page = null, ?int $scrollOffset = null, + ?array $tags = null, ?int $timeoutMs = null, Viewport|array|null $viewport = null, ?int $waitForMs = null, @@ -167,6 +181,7 @@ public static function with( null !== $maxAgeMs && $self['maxAgeMs'] = $maxAgeMs; null !== $page && $self['page'] = $page; null !== $scrollOffset && $self['scrollOffset'] = $scrollOffset; + null !== $tags && $self['tags'] = $tags; null !== $timeoutMs && $self['timeoutMs'] = $timeoutMs; null !== $viewport && $self['viewport'] = $viewport; null !== $waitForMs && $self['waitForMs'] = $waitForMs; @@ -188,7 +203,7 @@ public function withColorScheme(ColorScheme|string $colorScheme): self } /** - * 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. + * 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 Country|value-of $country */ @@ -239,10 +254,10 @@ public function withFullScreenshot( /** * Optional parameter to control cookie/consent popup handling. If 'true', we dismiss cookie banner before capture. If 'false' or not provided, captures the page without that step. * - * @param HandleCookiePopup|value-of $handleCookiePopup + * @param HandleCookiePopupShape $handleCookiePopup */ public function withHandleCookiePopup( - HandleCookiePopup|string $handleCookiePopup + bool|UnionMember1|string $handleCookiePopup ): self { $self = clone $this; $self['handleCookiePopup'] = $handleCookiePopup; @@ -253,7 +268,7 @@ public function withHandleCookiePopup( /** * Return a cached screenshot if a prior screenshot for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always capture fresh. */ - public function withMaxAgeMs(int $maxAgeMs): self + public function withMaxAgeMs(?int $maxAgeMs): self { $self = clone $this; $self['maxAgeMs'] = $maxAgeMs; @@ -277,7 +292,7 @@ public function withPage(Page|string $page): self /** * Optional vertical scroll offset in pixels for capturing a long page in viewport-sized chunks. When provided, the full page is captured once and the returned image is the viewport-sized slice that begins at this Y offset (e.g. request scrollOffset=0, then 1080, then 2160 to walk a 1920x1080 landing page top to bottom). The final slice may be shorter than the viewport height. Takes precedence over fullScreenshot. Max: 100000. */ - public function withScrollOffset(int $scrollOffset): self + public function withScrollOffset(?int $scrollOffset): self { $self = clone $this; $self['scrollOffset'] = $scrollOffset; @@ -285,6 +300,19 @@ public function withScrollOffset(int $scrollOffset): self return $self; } + /** + * Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters. + * + * @param list $tags + */ + public function withTags(array $tags): self + { + $self = clone $this; + $self['tags'] = $tags; + + return $self; + } + /** * 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). */ @@ -310,9 +338,9 @@ public function withViewport(Viewport|array $viewport): self } /** - * Optional browser wait time in milliseconds after initial page load before taking the screenshot. Min: 0. Max: 30000 (30 seconds). Defaults to 3000 ms when omitted. + * Optional browser wait time in milliseconds after initial page load before taking the screenshot. Min: 0. Max: 30000 (30 seconds). Defaults to 3000 ms when omitted. */ - public function withWaitForMs(int $waitForMs): self + public function withWaitForMs(?int $waitForMs): self { $self = clone $this; $self['waitForMs'] = $waitForMs; diff --git a/src/Web/WebScreenshotParams/Country.php b/src/Web/WebScreenshotParams/Country.php index 912e435..9715cfc 100644 --- a/src/Web/WebScreenshotParams/Country.php +++ b/src/Web/WebScreenshotParams/Country.php @@ -5,7 +5,7 @@ namespace ContextDev\Web\WebScreenshotParams; /** - * 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. + * 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. */ enum Country: string { diff --git a/src/Web/WebScreenshotParams/HandleCookiePopup.php b/src/Web/WebScreenshotParams/HandleCookiePopup.php index 574b402..0b9f790 100644 --- a/src/Web/WebScreenshotParams/HandleCookiePopup.php +++ b/src/Web/WebScreenshotParams/HandleCookiePopup.php @@ -4,12 +4,26 @@ namespace ContextDev\Web\WebScreenshotParams; +use ContextDev\Core\Concerns\SdkUnion; +use ContextDev\Core\Conversion\Contracts\Converter; +use ContextDev\Core\Conversion\Contracts\ConverterSource; +use ContextDev\Web\WebScreenshotParams\HandleCookiePopup\UnionMember1; + /** * Optional parameter to control cookie/consent popup handling. If 'true', we dismiss cookie banner before capture. If 'false' or not provided, captures the page without that step. + * + * @phpstan-type HandleCookiePopupVariants = bool|value-of + * @phpstan-type HandleCookiePopupShape = HandleCookiePopupVariants */ -enum HandleCookiePopup: string +final class HandleCookiePopup implements ConverterSource { - case TRUE = 'true'; + use SdkUnion; - case FALSE = 'false'; + /** + * @return list|array + */ + public static function variants(): array + { + return ['bool', UnionMember1::class]; + } } diff --git a/src/Web/WebScreenshotParams/HandleCookiePopup/UnionMember1.php b/src/Web/WebScreenshotParams/HandleCookiePopup/UnionMember1.php new file mode 100644 index 0000000..defd4c4 --- /dev/null +++ b/src/Web/WebScreenshotParams/HandleCookiePopup/UnionMember1.php @@ -0,0 +1,12 @@ +|null, * timeoutMs?: int|null, * } */ @@ -94,6 +95,14 @@ final class WebSearchParams implements BaseModel #[Optional] public ?bool $queryFanout; + /** + * Optional caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters. + * + * @var list|null $tags + */ + #[Optional(list: 'string')] + public ?array $tags; + /** * 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). */ @@ -129,6 +138,7 @@ public function __construct() * @param Freshness|value-of|null $freshness * @param list|null $includeDomains * @param MarkdownOptions|MarkdownOptionsShape|null $markdownOptions + * @param list|null $tags */ public static function with( string $query, @@ -139,6 +149,7 @@ public static function with( MarkdownOptions|array|null $markdownOptions = null, ?int $numResults = null, ?bool $queryFanout = null, + ?array $tags = null, ?int $timeoutMs = null, ): self { $self = new self; @@ -152,6 +163,7 @@ public static function with( null !== $markdownOptions && $self['markdownOptions'] = $markdownOptions; null !== $numResults && $self['numResults'] = $numResults; null !== $queryFanout && $self['queryFanout'] = $queryFanout; + null !== $tags && $self['tags'] = $tags; null !== $timeoutMs && $self['timeoutMs'] = $timeoutMs; return $self; @@ -256,6 +268,19 @@ public function withQueryFanout(bool $queryFanout): self return $self; } + /** + * Optional caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters. + * + * @param list $tags + */ + public function withTags(array $tags): self + { + $self = clone $this; + $self['tags'] = $tags; + + return $self; + } + /** * 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). */ diff --git a/src/Web/WebWebCrawlMdParams.php b/src/Web/WebWebCrawlMdParams.php index f5aa36d..4990e42 100644 --- a/src/Web/WebWebCrawlMdParams.php +++ b/src/Web/WebWebCrawlMdParams.php @@ -35,6 +35,7 @@ * settleAnimations?: bool|null, * shortenBase64Images?: bool|null, * stopAfterMs?: int|null, + * tags?: list|null, * timeoutMs?: int|null, * urlRegex?: string|null, * useMainContentOnly?: bool|null, @@ -143,6 +144,14 @@ final class WebWebCrawlMdParams implements BaseModel #[Optional] public ?int $stopAfterMs; + /** + * Optional caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters. + * + * @var list|null $tags + */ + #[Optional(list: 'string')] + public ?array $tags; + /** * 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). */ @@ -195,6 +204,7 @@ public function __construct() * @param list|null $excludeSelectors * @param list|null $includeSelectors * @param Pdf|PdfShape|null $pdf + * @param list|null $tags */ public static function with( string $url, @@ -212,6 +222,7 @@ public static function with( ?bool $settleAnimations = null, ?bool $shortenBase64Images = null, ?int $stopAfterMs = null, + ?array $tags = null, ?int $timeoutMs = null, ?string $urlRegex = null, ?bool $useMainContentOnly = null, @@ -235,6 +246,7 @@ public static function with( null !== $settleAnimations && $self['settleAnimations'] = $settleAnimations; null !== $shortenBase64Images && $self['shortenBase64Images'] = $shortenBase64Images; null !== $stopAfterMs && $self['stopAfterMs'] = $stopAfterMs; + null !== $tags && $self['tags'] = $tags; null !== $timeoutMs && $self['timeoutMs'] = $timeoutMs; null !== $urlRegex && $self['urlRegex'] = $urlRegex; null !== $useMainContentOnly && $self['useMainContentOnly'] = $useMainContentOnly; @@ -416,6 +428,19 @@ public function withStopAfterMs(int $stopAfterMs): self return $self; } + /** + * Optional caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters. + * + * @param list $tags + */ + public function withTags(array $tags): self + { + $self = clone $this; + $self['tags'] = $tags; + + return $self; + } + /** * 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). */ diff --git a/src/Web/WebWebScrapeHTMLParams.php b/src/Web/WebWebScrapeHTMLParams.php index 3f3139a..a4de330 100644 --- a/src/Web/WebWebScrapeHTMLParams.php +++ b/src/Web/WebWebScrapeHTMLParams.php @@ -10,27 +10,38 @@ use ContextDev\Core\Concerns\SdkParams; use ContextDev\Core\Contracts\BaseModel; use ContextDev\Web\WebWebScrapeHTMLParams\Country; +use ContextDev\Web\WebWebScrapeHTMLParams\IncludeFrames; +use ContextDev\Web\WebWebScrapeHTMLParams\IncludeFrames\UnionMember1; use ContextDev\Web\WebWebScrapeHTMLParams\Pdf; +use ContextDev\Web\WebWebScrapeHTMLParams\SettleAnimations; +use ContextDev\Web\WebWebScrapeHTMLParams\UseMainContentOnly; /** * Scrapes the given URL and returns the raw HTML content of the page. * * @see ContextDev\Services\WebService::webScrapeHTML() * + * @phpstan-import-type IncludeFramesVariants from \ContextDev\Web\WebWebScrapeHTMLParams\IncludeFrames + * @phpstan-import-type SettleAnimationsVariants from \ContextDev\Web\WebWebScrapeHTMLParams\SettleAnimations + * @phpstan-import-type UseMainContentOnlyVariants from \ContextDev\Web\WebWebScrapeHTMLParams\UseMainContentOnly + * @phpstan-import-type IncludeFramesShape from \ContextDev\Web\WebWebScrapeHTMLParams\IncludeFrames * @phpstan-import-type PdfShape from \ContextDev\Web\WebWebScrapeHTMLParams\Pdf + * @phpstan-import-type SettleAnimationsShape from \ContextDev\Web\WebWebScrapeHTMLParams\SettleAnimations + * @phpstan-import-type UseMainContentOnlyShape from \ContextDev\Web\WebWebScrapeHTMLParams\UseMainContentOnly * * @phpstan-type WebWebScrapeHTMLParamsShape = array{ * url: string, * country?: null|Country|value-of, * excludeSelectors?: list|null, * headers?: array|null, - * includeFrames?: bool|null, + * includeFrames?: IncludeFramesShape|null, * includeSelectors?: list|null, * maxAgeMs?: int|null, * pdf?: null|Pdf|PdfShape, - * settleAnimations?: bool|null, + * settleAnimations?: SettleAnimationsShape|null, + * tags?: list|null, * timeoutMs?: int|null, - * useMainContentOnly?: bool|null, + * useMainContentOnly?: UseMainContentOnlyShape|null, * waitForMs?: int|null, * } */ @@ -47,7 +58,7 @@ final class WebWebScrapeHTMLParams implements BaseModel public string $url; /** - * 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. + * 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. * * @var value-of|null $country */ @@ -59,7 +70,7 @@ final class WebWebScrapeHTMLParams implements BaseModel * * @var list|null $excludeSelectors */ - #[Optional(list: 'string')] + #[Optional(list: 'string', nullable: true)] public ?array $excludeSelectors; /** @@ -72,22 +83,24 @@ final class WebWebScrapeHTMLParams implements BaseModel /** * When true, iframes are rendered inline into the returned HTML. + * + * @var IncludeFramesVariants|null $includeFrames */ - #[Optional] - public ?bool $includeFrames; + #[Optional(union: IncludeFrames::class)] + public bool|string|null $includeFrames; /** * CSS selectors. When provided, only matching subtrees (and their descendants) are kept and everything else is dropped. When omitted, the entire document is kept. Examples: "article.main", "#content", "[role=main]". * * @var list|null $includeSelectors */ - #[Optional(list: 'string')] + #[Optional(list: 'string', nullable: true)] public ?array $includeSelectors; /** * Return a cached result if a prior scrape for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh. */ - #[Optional] + #[Optional(nullable: true)] public ?int $maxAgeMs; /** @@ -98,9 +111,19 @@ final class WebWebScrapeHTMLParams implements BaseModel /** * When true, waits briefly for CSS and transition animations to settle before extracting HTML. Defaults to false. This adds a bit of latency in exchange for more stable output on animated pages. + * + * @var SettleAnimationsVariants|null $settleAnimations */ - #[Optional] - public ?bool $settleAnimations; + #[Optional(union: SettleAnimations::class)] + public bool|string|null $settleAnimations; + + /** + * Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters. + * + * @var list|null $tags + */ + #[Optional(list: 'string')] + public ?array $tags; /** * 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). @@ -110,14 +133,16 @@ final class WebWebScrapeHTMLParams implements BaseModel /** * When true, return only the page's main content in the HTML response, excluding headers, footers, sidebars, and navigation when detectable. + * + * @var UseMainContentOnlyVariants|null $useMainContentOnly */ - #[Optional] - public ?bool $useMainContentOnly; + #[Optional(union: UseMainContentOnly::class)] + public bool|string|null $useMainContentOnly; /** * Optional browser wait time in milliseconds after initial page load. Min: 0. Max: 30000 (30 seconds). */ - #[Optional] + #[Optional(nullable: true)] public ?int $waitForMs; /** @@ -147,21 +172,26 @@ public function __construct() * @param Country|value-of|null $country * @param list|null $excludeSelectors * @param array|null $headers + * @param IncludeFramesShape|null $includeFrames * @param list|null $includeSelectors * @param Pdf|PdfShape|null $pdf + * @param SettleAnimationsShape|null $settleAnimations + * @param list|null $tags + * @param UseMainContentOnlyShape|null $useMainContentOnly */ public static function with( string $url, Country|string|null $country = null, ?array $excludeSelectors = null, ?array $headers = null, - ?bool $includeFrames = null, + bool|UnionMember1|string|null $includeFrames = null, ?array $includeSelectors = null, ?int $maxAgeMs = null, Pdf|array|null $pdf = null, - ?bool $settleAnimations = null, + bool|SettleAnimations\UnionMember1|string|null $settleAnimations = null, + ?array $tags = null, ?int $timeoutMs = null, - ?bool $useMainContentOnly = null, + bool|UseMainContentOnly\UnionMember1|string|null $useMainContentOnly = null, ?int $waitForMs = null, ): self { $self = new self; @@ -176,6 +206,7 @@ public static function with( null !== $maxAgeMs && $self['maxAgeMs'] = $maxAgeMs; null !== $pdf && $self['pdf'] = $pdf; null !== $settleAnimations && $self['settleAnimations'] = $settleAnimations; + null !== $tags && $self['tags'] = $tags; null !== $timeoutMs && $self['timeoutMs'] = $timeoutMs; null !== $useMainContentOnly && $self['useMainContentOnly'] = $useMainContentOnly; null !== $waitForMs && $self['waitForMs'] = $waitForMs; @@ -195,7 +226,7 @@ public function withURL(string $url): self } /** - * 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. + * 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 Country|value-of $country */ @@ -210,9 +241,9 @@ public function withCountry(Country|string $country): self /** * 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 list $excludeSelectors + * @param list|null $excludeSelectors */ - public function withExcludeSelectors(array $excludeSelectors): self + public function withExcludeSelectors(?array $excludeSelectors): self { $self = clone $this; $self['excludeSelectors'] = $excludeSelectors; @@ -235,9 +266,12 @@ public function withHeaders(array $headers): self /** * When true, iframes are rendered inline into the returned HTML. + * + * @param IncludeFramesShape $includeFrames */ - public function withIncludeFrames(bool $includeFrames): self - { + public function withIncludeFrames( + bool|UnionMember1|string $includeFrames + ): self { $self = clone $this; $self['includeFrames'] = $includeFrames; @@ -247,9 +281,9 @@ public function withIncludeFrames(bool $includeFrames): self /** * CSS selectors. When provided, only matching subtrees (and their descendants) are kept and everything else is dropped. When omitted, the entire document is kept. Examples: "article.main", "#content", "[role=main]". * - * @param list $includeSelectors + * @param list|null $includeSelectors */ - public function withIncludeSelectors(array $includeSelectors): self + public function withIncludeSelectors(?array $includeSelectors): self { $self = clone $this; $self['includeSelectors'] = $includeSelectors; @@ -260,7 +294,7 @@ public function withIncludeSelectors(array $includeSelectors): self /** * Return a cached result if a prior scrape for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh. */ - public function withMaxAgeMs(int $maxAgeMs): self + public function withMaxAgeMs(?int $maxAgeMs): self { $self = clone $this; $self['maxAgeMs'] = $maxAgeMs; @@ -283,15 +317,31 @@ public function withPdf(Pdf|array $pdf): self /** * When true, waits briefly for CSS and transition animations to settle before extracting HTML. Defaults to false. This adds a bit of latency in exchange for more stable output on animated pages. + * + * @param SettleAnimationsShape $settleAnimations */ - public function withSettleAnimations(bool $settleAnimations): self - { + public function withSettleAnimations( + bool|SettleAnimations\UnionMember1|string $settleAnimations, + ): self { $self = clone $this; $self['settleAnimations'] = $settleAnimations; return $self; } + /** + * Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters. + * + * @param list $tags + */ + public function withTags(array $tags): self + { + $self = clone $this; + $self['tags'] = $tags; + + return $self; + } + /** * 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). */ @@ -305,9 +355,12 @@ public function withTimeoutMs(int $timeoutMs): self /** * When true, return only the page's main content in the HTML response, excluding headers, footers, sidebars, and navigation when detectable. + * + * @param UseMainContentOnlyShape $useMainContentOnly */ - public function withUseMainContentOnly(bool $useMainContentOnly): self - { + public function withUseMainContentOnly( + bool|UseMainContentOnly\UnionMember1|string $useMainContentOnly, + ): self { $self = clone $this; $self['useMainContentOnly'] = $useMainContentOnly; @@ -317,7 +370,7 @@ public function withUseMainContentOnly(bool $useMainContentOnly): self /** * Optional browser wait time in milliseconds after initial page load. Min: 0. Max: 30000 (30 seconds). */ - public function withWaitForMs(int $waitForMs): self + public function withWaitForMs(?int $waitForMs): self { $self = clone $this; $self['waitForMs'] = $waitForMs; diff --git a/src/Web/WebWebScrapeHTMLParams/Country.php b/src/Web/WebWebScrapeHTMLParams/Country.php index 6c784e4..5588f0a 100644 --- a/src/Web/WebWebScrapeHTMLParams/Country.php +++ b/src/Web/WebWebScrapeHTMLParams/Country.php @@ -5,7 +5,7 @@ namespace ContextDev\Web\WebWebScrapeHTMLParams; /** - * 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. + * 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. */ enum Country: string { diff --git a/src/Web/WebWebScrapeHTMLParams/IncludeFrames.php b/src/Web/WebWebScrapeHTMLParams/IncludeFrames.php new file mode 100644 index 0000000..84047a8 --- /dev/null +++ b/src/Web/WebWebScrapeHTMLParams/IncludeFrames.php @@ -0,0 +1,29 @@ + + * @phpstan-type IncludeFramesShape = IncludeFramesVariants + */ +final class IncludeFrames implements ConverterSource +{ + use SdkUnion; + + /** + * @return list|array + */ + public static function variants(): array + { + return ['bool', UnionMember1::class]; + } +} diff --git a/src/Web/WebWebScrapeHTMLParams/IncludeFrames/UnionMember1.php b/src/Web/WebWebScrapeHTMLParams/IncludeFrames/UnionMember1.php new file mode 100644 index 0000000..9d19256 --- /dev/null +++ b/src/Web/WebWebScrapeHTMLParams/IncludeFrames/UnionMember1.php @@ -0,0 +1,12 @@ + + * @phpstan-type OcrShape = OcrVariants + */ +final class Ocr implements ConverterSource +{ + use SdkUnion; + + /** + * @return list|array + */ + public static function variants(): array + { + return ['bool', UnionMember1::class]; + } +} diff --git a/src/Web/WebWebScrapeHTMLParams/Pdf/Ocr/UnionMember1.php b/src/Web/WebWebScrapeHTMLParams/Pdf/Ocr/UnionMember1.php new file mode 100644 index 0000000..dfb79b2 --- /dev/null +++ b/src/Web/WebWebScrapeHTMLParams/Pdf/Ocr/UnionMember1.php @@ -0,0 +1,12 @@ + + * @phpstan-type ShouldParseShape = ShouldParseVariants + */ +final class ShouldParse implements ConverterSource +{ + use SdkUnion; + + /** + * @return list|array + */ + public static function variants(): array + { + return ['bool', UnionMember1::class]; + } +} diff --git a/src/Web/WebWebScrapeHTMLParams/Pdf/ShouldParse/UnionMember1.php b/src/Web/WebWebScrapeHTMLParams/Pdf/ShouldParse/UnionMember1.php new file mode 100644 index 0000000..9de72ad --- /dev/null +++ b/src/Web/WebWebScrapeHTMLParams/Pdf/ShouldParse/UnionMember1.php @@ -0,0 +1,12 @@ + + * @phpstan-type SettleAnimationsShape = SettleAnimationsVariants + */ +final class SettleAnimations implements ConverterSource +{ + use SdkUnion; + + /** + * @return list|array + */ + public static function variants(): array + { + return ['bool', UnionMember1::class]; + } +} diff --git a/src/Web/WebWebScrapeHTMLParams/SettleAnimations/UnionMember1.php b/src/Web/WebWebScrapeHTMLParams/SettleAnimations/UnionMember1.php new file mode 100644 index 0000000..899122c --- /dev/null +++ b/src/Web/WebWebScrapeHTMLParams/SettleAnimations/UnionMember1.php @@ -0,0 +1,12 @@ + + * @phpstan-type UseMainContentOnlyShape = UseMainContentOnlyVariants + */ +final class UseMainContentOnly implements ConverterSource +{ + use SdkUnion; + + /** + * @return list|array + */ + public static function variants(): array + { + return ['bool', UnionMember1::class]; + } +} diff --git a/src/Web/WebWebScrapeHTMLParams/UseMainContentOnly/UnionMember1.php b/src/Web/WebWebScrapeHTMLParams/UseMainContentOnly/UnionMember1.php new file mode 100644 index 0000000..38c3ff7 --- /dev/null +++ b/src/Web/WebWebScrapeHTMLParams/UseMainContentOnly/UnionMember1.php @@ -0,0 +1,12 @@ +|null, * maxAgeMs?: int|null, + * tags?: list|null, * timeoutMs?: int|null, * waitForMs?: int|null, * } @@ -42,14 +47,16 @@ final class WebWebScrapeImagesParams implements BaseModel /** * When true, visually duplicate images are removed: every image is loaded and perceptually hashed, and only the highest-resolution copy of each duplicate group is kept. Images that cannot be downloaded or hashed are kept. Default: false. + * + * @var DedupeVariants|null $dedupe */ - #[Optional] - public ?bool $dedupe; + #[Optional(union: Dedupe::class)] + public bool|string|null $dedupe; /** * Optional per-image processing, sent as deep-object query params such as enrichment[resolution]=true. */ - #[Optional] + #[Optional(nullable: true)] public ?Enrichment $enrichment; /** @@ -63,9 +70,17 @@ final class WebWebScrapeImagesParams implements BaseModel /** * Reuse a cached result this many milliseconds old or newer. Default: 86400000 (1 day). Set to 0 to bypass cache. Maximum: 2592000000 (30 days). */ - #[Optional] + #[Optional(nullable: true)] public ?int $maxAgeMs; + /** + * Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters. + * + * @var list|null $tags + */ + #[Optional(list: 'string')] + public ?array $tags; + /** * 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). */ @@ -75,7 +90,7 @@ final class WebWebScrapeImagesParams implements BaseModel /** * Optional browser wait time in milliseconds after initial page load before collecting images. Min: 0. Max: 30000 (30 seconds). */ - #[Optional] + #[Optional(nullable: true)] public ?int $waitForMs; /** @@ -102,15 +117,18 @@ public function __construct() * * You must use named parameters to construct any parameters with a default value. * + * @param DedupeShape|null $dedupe * @param Enrichment|EnrichmentShape|null $enrichment * @param array|null $headers + * @param list|null $tags */ public static function with( string $url, - ?bool $dedupe = null, + bool|UnionMember1|string|null $dedupe = null, Enrichment|array|null $enrichment = null, ?array $headers = null, ?int $maxAgeMs = null, + ?array $tags = null, ?int $timeoutMs = null, ?int $waitForMs = null, ): self { @@ -122,6 +140,7 @@ public static function with( null !== $enrichment && $self['enrichment'] = $enrichment; null !== $headers && $self['headers'] = $headers; null !== $maxAgeMs && $self['maxAgeMs'] = $maxAgeMs; + null !== $tags && $self['tags'] = $tags; null !== $timeoutMs && $self['timeoutMs'] = $timeoutMs; null !== $waitForMs && $self['waitForMs'] = $waitForMs; @@ -141,8 +160,10 @@ public function withURL(string $url): self /** * When true, visually duplicate images are removed: every image is loaded and perceptually hashed, and only the highest-resolution copy of each duplicate group is kept. Images that cannot be downloaded or hashed are kept. Default: false. + * + * @param DedupeShape $dedupe */ - public function withDedupe(bool $dedupe): self + public function withDedupe(bool|UnionMember1|string $dedupe): self { $self = clone $this; $self['dedupe'] = $dedupe; @@ -153,9 +174,9 @@ public function withDedupe(bool $dedupe): self /** * Optional per-image processing, sent as deep-object query params such as enrichment[resolution]=true. * - * @param Enrichment|EnrichmentShape $enrichment + * @param Enrichment|EnrichmentShape|null $enrichment */ - public function withEnrichment(Enrichment|array $enrichment): self + public function withEnrichment(Enrichment|array|null $enrichment): self { $self = clone $this; $self['enrichment'] = $enrichment; @@ -179,7 +200,7 @@ public function withHeaders(array $headers): self /** * Reuse a cached result this many milliseconds old or newer. Default: 86400000 (1 day). Set to 0 to bypass cache. Maximum: 2592000000 (30 days). */ - public function withMaxAgeMs(int $maxAgeMs): self + public function withMaxAgeMs(?int $maxAgeMs): self { $self = clone $this; $self['maxAgeMs'] = $maxAgeMs; @@ -187,6 +208,19 @@ public function withMaxAgeMs(int $maxAgeMs): self return $self; } + /** + * Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters. + * + * @param list $tags + */ + public function withTags(array $tags): self + { + $self = clone $this; + $self['tags'] = $tags; + + return $self; + } + /** * 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). */ @@ -201,7 +235,7 @@ public function withTimeoutMs(int $timeoutMs): self /** * Optional browser wait time in milliseconds after initial page load before collecting images. Min: 0. Max: 30000 (30 seconds). */ - public function withWaitForMs(int $waitForMs): self + public function withWaitForMs(?int $waitForMs): self { $self = clone $this; $self['waitForMs'] = $waitForMs; diff --git a/src/Web/WebWebScrapeImagesParams/Dedupe.php b/src/Web/WebWebScrapeImagesParams/Dedupe.php new file mode 100644 index 0000000..c1fd6ec --- /dev/null +++ b/src/Web/WebWebScrapeImagesParams/Dedupe.php @@ -0,0 +1,29 @@ + + * @phpstan-type DedupeShape = DedupeVariants + */ +final class Dedupe implements ConverterSource +{ + use SdkUnion; + + /** + * @return list|array + */ + public static function variants(): array + { + return ['bool', UnionMember1::class]; + } +} diff --git a/src/Web/WebWebScrapeImagesParams/Dedupe/UnionMember1.php b/src/Web/WebWebScrapeImagesParams/Dedupe/UnionMember1.php new file mode 100644 index 0000000..4950f30 --- /dev/null +++ b/src/Web/WebWebScrapeImagesParams/Dedupe/UnionMember1.php @@ -0,0 +1,12 @@ + + * @phpstan-type ClassificationShape = ClassificationVariants + */ +final class Classification implements ConverterSource +{ + use SdkUnion; + + /** + * @return list|array + */ + public static function variants(): array + { + return ['bool', UnionMember1::class]; + } +} diff --git a/src/Web/WebWebScrapeImagesParams/Enrichment/Classification/UnionMember1.php b/src/Web/WebWebScrapeImagesParams/Enrichment/Classification/UnionMember1.php new file mode 100644 index 0000000..4d5c01f --- /dev/null +++ b/src/Web/WebWebScrapeImagesParams/Enrichment/Classification/UnionMember1.php @@ -0,0 +1,12 @@ + + * @phpstan-type HostedURLShape = HostedURLVariants + */ +final class HostedURL implements ConverterSource +{ + use SdkUnion; + + /** + * @return list|array + */ + public static function variants(): array + { + return ['bool', UnionMember1::class]; + } +} diff --git a/src/Web/WebWebScrapeImagesParams/Enrichment/HostedURL/UnionMember1.php b/src/Web/WebWebScrapeImagesParams/Enrichment/HostedURL/UnionMember1.php new file mode 100644 index 0000000..c353109 --- /dev/null +++ b/src/Web/WebWebScrapeImagesParams/Enrichment/HostedURL/UnionMember1.php @@ -0,0 +1,12 @@ + + * @phpstan-type ResolutionShape = ResolutionVariants + */ +final class Resolution implements ConverterSource +{ + use SdkUnion; + + /** + * @return list|array + */ + public static function variants(): array + { + return ['bool', UnionMember1::class]; + } +} diff --git a/src/Web/WebWebScrapeImagesParams/Enrichment/Resolution/UnionMember1.php b/src/Web/WebWebScrapeImagesParams/Enrichment/Resolution/UnionMember1.php new file mode 100644 index 0000000..7dcafd5 --- /dev/null +++ b/src/Web/WebWebScrapeImagesParams/Enrichment/Resolution/UnionMember1.php @@ -0,0 +1,12 @@ +, * excludeSelectors?: list|null, * headers?: array|null, - * includeFrames?: bool|null, - * includeImages?: bool|null, - * includeLinks?: bool|null, + * includeFrames?: IncludeFramesShape|null, + * includeImages?: IncludeImagesShape|null, + * includeLinks?: IncludeLinksShape|null, * includeSelectors?: list|null, * maxAgeMs?: int|null, * pdf?: null|Pdf|PdfShape, - * settleAnimations?: bool|null, - * shortenBase64Images?: bool|null, + * settleAnimations?: SettleAnimationsShape|null, + * shortenBase64Images?: ShortenBase64ImagesShape|null, + * tags?: list|null, * timeoutMs?: int|null, - * useMainContentOnly?: bool|null, + * useMainContentOnly?: UseMainContentOnlyShape|null, * waitForMs?: int|null, * } */ @@ -63,7 +83,7 @@ final class WebWebScrapeMdParams implements BaseModel public string $url; /** - * 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. + * 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. * * @var value-of|null $country */ @@ -75,7 +95,7 @@ final class WebWebScrapeMdParams implements BaseModel * * @var list|null $excludeSelectors */ - #[Optional(list: 'string')] + #[Optional(list: 'string', nullable: true)] public ?array $excludeSelectors; /** @@ -88,34 +108,40 @@ final class WebWebScrapeMdParams implements BaseModel /** * When true, the contents of iframes are rendered to Markdown. + * + * @var IncludeFramesVariants|null $includeFrames */ - #[Optional] - public ?bool $includeFrames; + #[Optional(union: IncludeFrames::class)] + public bool|string|null $includeFrames; /** * Include image references in Markdown output. + * + * @var IncludeImagesVariants|null $includeImages */ - #[Optional] - public ?bool $includeImages; + #[Optional(union: IncludeImages::class)] + public bool|string|null $includeImages; /** * Preserve hyperlinks in Markdown output. + * + * @var IncludeLinksVariants|null $includeLinks */ - #[Optional] - public ?bool $includeLinks; + #[Optional(union: IncludeLinks::class)] + public bool|string|null $includeLinks; /** * 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]". * * @var list|null $includeSelectors */ - #[Optional(list: 'string')] + #[Optional(list: 'string', nullable: true)] public ?array $includeSelectors; /** * Return a cached result if a prior scrape for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh. */ - #[Optional] + #[Optional(nullable: true)] public ?int $maxAgeMs; /** @@ -126,15 +152,27 @@ final class WebWebScrapeMdParams implements BaseModel /** * When true, waits briefly for CSS and transition animations to settle before converting to Markdown. Defaults to false. This adds a bit of latency in exchange for more stable output on animated pages. + * + * @var SettleAnimationsVariants|null $settleAnimations */ - #[Optional] - public ?bool $settleAnimations; + #[Optional(union: SettleAnimations::class)] + public bool|string|null $settleAnimations; /** * Shorten base64-encoded image data in the Markdown output. + * + * @var ShortenBase64ImagesVariants|null $shortenBase64Images */ - #[Optional] - public ?bool $shortenBase64Images; + #[Optional(union: ShortenBase64Images::class)] + public bool|string|null $shortenBase64Images; + + /** + * Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters. + * + * @var list|null $tags + */ + #[Optional(list: 'string')] + public ?array $tags; /** * 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). @@ -144,14 +182,16 @@ final class WebWebScrapeMdParams implements BaseModel /** * Extract only the main content of the page, excluding headers, footers, sidebars, and navigation. + * + * @var UseMainContentOnlyVariants|null $useMainContentOnly */ - #[Optional] - public ?bool $useMainContentOnly; + #[Optional(union: UseMainContentOnly::class)] + public bool|string|null $useMainContentOnly; /** * Optional browser wait time in milliseconds after initial page load before converting the page to Markdown. Min: 0. Max: 30000 (30 seconds). */ - #[Optional] + #[Optional(nullable: true)] public ?int $waitForMs; /** @@ -181,24 +221,32 @@ public function __construct() * @param Country|value-of|null $country * @param list|null $excludeSelectors * @param array|null $headers + * @param IncludeFramesShape|null $includeFrames + * @param IncludeImagesShape|null $includeImages + * @param IncludeLinksShape|null $includeLinks * @param list|null $includeSelectors * @param Pdf|PdfShape|null $pdf + * @param SettleAnimationsShape|null $settleAnimations + * @param ShortenBase64ImagesShape|null $shortenBase64Images + * @param list|null $tags + * @param UseMainContentOnlyShape|null $useMainContentOnly */ public static function with( string $url, Country|string|null $country = null, ?array $excludeSelectors = null, ?array $headers = null, - ?bool $includeFrames = null, - ?bool $includeImages = null, - ?bool $includeLinks = null, + bool|UnionMember1|string|null $includeFrames = null, + bool|IncludeImages\UnionMember1|string|null $includeImages = null, + bool|IncludeLinks\UnionMember1|string|null $includeLinks = null, ?array $includeSelectors = null, ?int $maxAgeMs = null, Pdf|array|null $pdf = null, - ?bool $settleAnimations = null, - ?bool $shortenBase64Images = null, + bool|SettleAnimations\UnionMember1|string|null $settleAnimations = null, + bool|ShortenBase64Images\UnionMember1|string|null $shortenBase64Images = null, + ?array $tags = null, ?int $timeoutMs = null, - ?bool $useMainContentOnly = null, + bool|UseMainContentOnly\UnionMember1|string|null $useMainContentOnly = null, ?int $waitForMs = null, ): self { $self = new self; @@ -216,6 +264,7 @@ public static function with( null !== $pdf && $self['pdf'] = $pdf; null !== $settleAnimations && $self['settleAnimations'] = $settleAnimations; null !== $shortenBase64Images && $self['shortenBase64Images'] = $shortenBase64Images; + null !== $tags && $self['tags'] = $tags; null !== $timeoutMs && $self['timeoutMs'] = $timeoutMs; null !== $useMainContentOnly && $self['useMainContentOnly'] = $useMainContentOnly; null !== $waitForMs && $self['waitForMs'] = $waitForMs; @@ -235,7 +284,7 @@ public function withURL(string $url): self } /** - * 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. + * 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 Country|value-of $country */ @@ -250,9 +299,9 @@ public function withCountry(Country|string $country): self /** * 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 list $excludeSelectors + * @param list|null $excludeSelectors */ - public function withExcludeSelectors(array $excludeSelectors): self + public function withExcludeSelectors(?array $excludeSelectors): self { $self = clone $this; $self['excludeSelectors'] = $excludeSelectors; @@ -275,9 +324,12 @@ public function withHeaders(array $headers): self /** * When true, the contents of iframes are rendered to Markdown. + * + * @param IncludeFramesShape $includeFrames */ - public function withIncludeFrames(bool $includeFrames): self - { + public function withIncludeFrames( + bool|UnionMember1|string $includeFrames + ): self { $self = clone $this; $self['includeFrames'] = $includeFrames; @@ -286,9 +338,12 @@ public function withIncludeFrames(bool $includeFrames): self /** * Include image references in Markdown output. + * + * @param IncludeImagesShape $includeImages */ - public function withIncludeImages(bool $includeImages): self - { + public function withIncludeImages( + bool|IncludeImages\UnionMember1|string $includeImages, + ): self { $self = clone $this; $self['includeImages'] = $includeImages; @@ -297,9 +352,12 @@ public function withIncludeImages(bool $includeImages): self /** * Preserve hyperlinks in Markdown output. + * + * @param IncludeLinksShape $includeLinks */ - public function withIncludeLinks(bool $includeLinks): self - { + public function withIncludeLinks( + bool|IncludeLinks\UnionMember1|string $includeLinks, + ): self { $self = clone $this; $self['includeLinks'] = $includeLinks; @@ -309,9 +367,9 @@ public function withIncludeLinks(bool $includeLinks): self /** * 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]". * - * @param list $includeSelectors + * @param list|null $includeSelectors */ - public function withIncludeSelectors(array $includeSelectors): self + public function withIncludeSelectors(?array $includeSelectors): self { $self = clone $this; $self['includeSelectors'] = $includeSelectors; @@ -322,7 +380,7 @@ public function withIncludeSelectors(array $includeSelectors): self /** * Return a cached result if a prior scrape for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh. */ - public function withMaxAgeMs(int $maxAgeMs): self + public function withMaxAgeMs(?int $maxAgeMs): self { $self = clone $this; $self['maxAgeMs'] = $maxAgeMs; @@ -345,9 +403,12 @@ public function withPdf(Pdf|array $pdf): self /** * When true, waits briefly for CSS and transition animations to settle before converting to Markdown. Defaults to false. This adds a bit of latency in exchange for more stable output on animated pages. + * + * @param SettleAnimationsShape $settleAnimations */ - public function withSettleAnimations(bool $settleAnimations): self - { + public function withSettleAnimations( + bool|SettleAnimations\UnionMember1|string $settleAnimations, + ): self { $self = clone $this; $self['settleAnimations'] = $settleAnimations; @@ -356,15 +417,31 @@ public function withSettleAnimations(bool $settleAnimations): self /** * Shorten base64-encoded image data in the Markdown output. + * + * @param ShortenBase64ImagesShape $shortenBase64Images */ - public function withShortenBase64Images(bool $shortenBase64Images): self - { + public function withShortenBase64Images( + bool|ShortenBase64Images\UnionMember1|string $shortenBase64Images, + ): self { $self = clone $this; $self['shortenBase64Images'] = $shortenBase64Images; return $self; } + /** + * Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters. + * + * @param list $tags + */ + public function withTags(array $tags): self + { + $self = clone $this; + $self['tags'] = $tags; + + return $self; + } + /** * 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). */ @@ -378,9 +455,12 @@ public function withTimeoutMs(int $timeoutMs): self /** * Extract only the main content of the page, excluding headers, footers, sidebars, and navigation. + * + * @param UseMainContentOnlyShape $useMainContentOnly */ - public function withUseMainContentOnly(bool $useMainContentOnly): self - { + public function withUseMainContentOnly( + bool|UseMainContentOnly\UnionMember1|string $useMainContentOnly, + ): self { $self = clone $this; $self['useMainContentOnly'] = $useMainContentOnly; @@ -390,7 +470,7 @@ public function withUseMainContentOnly(bool $useMainContentOnly): self /** * Optional browser wait time in milliseconds after initial page load before converting the page to Markdown. Min: 0. Max: 30000 (30 seconds). */ - public function withWaitForMs(int $waitForMs): self + public function withWaitForMs(?int $waitForMs): self { $self = clone $this; $self['waitForMs'] = $waitForMs; diff --git a/src/Web/WebWebScrapeMdParams/Country.php b/src/Web/WebWebScrapeMdParams/Country.php index 3d1460e..9700534 100644 --- a/src/Web/WebWebScrapeMdParams/Country.php +++ b/src/Web/WebWebScrapeMdParams/Country.php @@ -5,7 +5,7 @@ namespace ContextDev\Web\WebWebScrapeMdParams; /** - * 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. + * 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. */ enum Country: string { diff --git a/src/Web/WebWebScrapeMdParams/IncludeFrames.php b/src/Web/WebWebScrapeMdParams/IncludeFrames.php new file mode 100644 index 0000000..dc3254f --- /dev/null +++ b/src/Web/WebWebScrapeMdParams/IncludeFrames.php @@ -0,0 +1,29 @@ + + * @phpstan-type IncludeFramesShape = IncludeFramesVariants + */ +final class IncludeFrames implements ConverterSource +{ + use SdkUnion; + + /** + * @return list|array + */ + public static function variants(): array + { + return ['bool', UnionMember1::class]; + } +} diff --git a/src/Web/WebWebScrapeMdParams/IncludeFrames/UnionMember1.php b/src/Web/WebWebScrapeMdParams/IncludeFrames/UnionMember1.php new file mode 100644 index 0000000..d887bb5 --- /dev/null +++ b/src/Web/WebWebScrapeMdParams/IncludeFrames/UnionMember1.php @@ -0,0 +1,12 @@ + + * @phpstan-type IncludeImagesShape = IncludeImagesVariants + */ +final class IncludeImages implements ConverterSource +{ + use SdkUnion; + + /** + * @return list|array + */ + public static function variants(): array + { + return ['bool', UnionMember1::class]; + } +} diff --git a/src/Web/WebWebScrapeMdParams/IncludeImages/UnionMember1.php b/src/Web/WebWebScrapeMdParams/IncludeImages/UnionMember1.php new file mode 100644 index 0000000..9f1df33 --- /dev/null +++ b/src/Web/WebWebScrapeMdParams/IncludeImages/UnionMember1.php @@ -0,0 +1,12 @@ + + * @phpstan-type IncludeLinksShape = IncludeLinksVariants + */ +final class IncludeLinks implements ConverterSource +{ + use SdkUnion; + + /** + * @return list|array + */ + public static function variants(): array + { + return ['bool', UnionMember1::class]; + } +} diff --git a/src/Web/WebWebScrapeMdParams/IncludeLinks/UnionMember1.php b/src/Web/WebWebScrapeMdParams/IncludeLinks/UnionMember1.php new file mode 100644 index 0000000..99b18fa --- /dev/null +++ b/src/Web/WebWebScrapeMdParams/IncludeLinks/UnionMember1.php @@ -0,0 +1,12 @@ + + * @phpstan-type OcrShape = OcrVariants + */ +final class Ocr implements ConverterSource +{ + use SdkUnion; + + /** + * @return list|array + */ + public static function variants(): array + { + return ['bool', UnionMember1::class]; + } +} diff --git a/src/Web/WebWebScrapeMdParams/Pdf/Ocr/UnionMember1.php b/src/Web/WebWebScrapeMdParams/Pdf/Ocr/UnionMember1.php new file mode 100644 index 0000000..8bd15b5 --- /dev/null +++ b/src/Web/WebWebScrapeMdParams/Pdf/Ocr/UnionMember1.php @@ -0,0 +1,12 @@ + + * @phpstan-type ShouldParseShape = ShouldParseVariants + */ +final class ShouldParse implements ConverterSource +{ + use SdkUnion; + + /** + * @return list|array + */ + public static function variants(): array + { + return ['bool', UnionMember1::class]; + } +} diff --git a/src/Web/WebWebScrapeMdParams/Pdf/ShouldParse/UnionMember1.php b/src/Web/WebWebScrapeMdParams/Pdf/ShouldParse/UnionMember1.php new file mode 100644 index 0000000..4db8b2b --- /dev/null +++ b/src/Web/WebWebScrapeMdParams/Pdf/ShouldParse/UnionMember1.php @@ -0,0 +1,12 @@ + + * @phpstan-type SettleAnimationsShape = SettleAnimationsVariants + */ +final class SettleAnimations implements ConverterSource +{ + use SdkUnion; + + /** + * @return list|array + */ + public static function variants(): array + { + return ['bool', UnionMember1::class]; + } +} diff --git a/src/Web/WebWebScrapeMdParams/SettleAnimations/UnionMember1.php b/src/Web/WebWebScrapeMdParams/SettleAnimations/UnionMember1.php new file mode 100644 index 0000000..915f75e --- /dev/null +++ b/src/Web/WebWebScrapeMdParams/SettleAnimations/UnionMember1.php @@ -0,0 +1,12 @@ + + * @phpstan-type ShortenBase64ImagesShape = ShortenBase64ImagesVariants + */ +final class ShortenBase64Images implements ConverterSource +{ + use SdkUnion; + + /** + * @return list|array + */ + public static function variants(): array + { + return ['bool', UnionMember1::class]; + } +} diff --git a/src/Web/WebWebScrapeMdParams/ShortenBase64Images/UnionMember1.php b/src/Web/WebWebScrapeMdParams/ShortenBase64Images/UnionMember1.php new file mode 100644 index 0000000..d064e43 --- /dev/null +++ b/src/Web/WebWebScrapeMdParams/ShortenBase64Images/UnionMember1.php @@ -0,0 +1,12 @@ + + * @phpstan-type UseMainContentOnlyShape = UseMainContentOnlyVariants + */ +final class UseMainContentOnly implements ConverterSource +{ + use SdkUnion; + + /** + * @return list|array + */ + public static function variants(): array + { + return ['bool', UnionMember1::class]; + } +} diff --git a/src/Web/WebWebScrapeMdParams/UseMainContentOnly/UnionMember1.php b/src/Web/WebWebScrapeMdParams/UseMainContentOnly/UnionMember1.php new file mode 100644 index 0000000..52449fe --- /dev/null +++ b/src/Web/WebWebScrapeMdParams/UseMainContentOnly/UnionMember1.php @@ -0,0 +1,12 @@ +|null, * maxLinks?: int|null, + * sitemapURL?: string|null, + * tags?: list|null, * timeoutMs?: int|null, * urlRegex?: string|null, * } @@ -49,6 +51,20 @@ final class WebWebScrapeSitemapParams implements BaseModel #[Optional] public ?int $maxLinks; + /** + * Optional explicit sitemap URL. When provided, exactly this sitemap is crawled instead of discovering the domain's sitemaps. + */ + #[Optional] + public ?string $sitemapURL; + + /** + * Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters. + * + * @var list|null $tags + */ + #[Optional(list: 'string')] + public ?array $tags; + /** * 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). */ @@ -86,11 +102,14 @@ public function __construct() * You must use named parameters to construct any parameters with a default value. * * @param array|null $headers + * @param list|null $tags */ public static function with( string $domain, ?array $headers = null, ?int $maxLinks = null, + ?string $sitemapURL = null, + ?array $tags = null, ?int $timeoutMs = null, ?string $urlRegex = null, ): self { @@ -100,6 +119,8 @@ public static function with( null !== $headers && $self['headers'] = $headers; null !== $maxLinks && $self['maxLinks'] = $maxLinks; + null !== $sitemapURL && $self['sitemapURL'] = $sitemapURL; + null !== $tags && $self['tags'] = $tags; null !== $timeoutMs && $self['timeoutMs'] = $timeoutMs; null !== $urlRegex && $self['urlRegex'] = $urlRegex; @@ -141,6 +162,30 @@ public function withMaxLinks(int $maxLinks): self return $self; } + /** + * Optional explicit sitemap URL. When provided, exactly this sitemap is crawled instead of discovering the domain's sitemaps. + */ + public function withSitemapURL(string $sitemapURL): self + { + $self = clone $this; + $self['sitemapURL'] = $sitemapURL; + + return $self; + } + + /** + * Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters. + * + * @param list $tags + */ + public function withTags(array $tags): self + { + $self = clone $this; + $self['tags'] = $tags; + + return $self; + } + /** * 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). */ diff --git a/tests/ClientTest.php b/tests/ClientTest.php index 07473e5..2b244ae 100644 --- a/tests/ClientTest.php +++ b/tests/ClientTest.php @@ -33,7 +33,7 @@ public function testDefaultHeaders(): void ); $client->brand->retrieve( - domain: 'domain', + domain: 'xxx', type: 'by_transaction', name: 'xxx', email: 'dev@stainless.com', diff --git a/tests/Services/AITest.php b/tests/Services/AITest.php index eff078e..f08ca15 100644 --- a/tests/Services/AITest.php +++ b/tests/Services/AITest.php @@ -52,7 +52,8 @@ public function testExtractProductWithOptionalParams(): void $result = $this->client->ai->extractProduct( url: 'https://example.com', maxAgeMs: 0, - timeoutMs: 1000 + tags: ['production', 'team-alpha'], + timeoutMs: 1000, ); // @phpstan-ignore-next-line method.alreadyNarrowedType @@ -86,6 +87,7 @@ public function testExtractProductsWithOptionalParams(): void domain: 'domain', maxAgeMs: 0, maxProducts: 1, + tags: ['production', 'team-alpha'], timeoutMs: 1000, directURL: 'https://example.com', ); diff --git a/tests/Services/BrandTest.php b/tests/Services/BrandTest.php index 7a91ba7..b5ab8fc 100644 --- a/tests/Services/BrandTest.php +++ b/tests/Services/BrandTest.php @@ -37,7 +37,7 @@ public function testRetrieve(): void } $result = $this->client->brand->retrieve( - domain: 'domain', + domain: 'xxx', type: 'by_transaction', name: 'xxx', email: 'dev@stainless.com', @@ -58,11 +58,12 @@ public function testRetrieveWithOptionalParams(): void } $result = $this->client->brand->retrieve( - domain: 'domain', + domain: 'xxx', type: 'by_transaction', forceLanguage: 'afrikaans', maxAgeMs: 0, maxSpeed: true, + tags: ['production', 'team-alpha'], timeoutMs: 1000, name: 'xxx', countryGl: 'country_gl', @@ -73,8 +74,8 @@ public function testRetrieveWithOptionalParams(): void transactionInfo: 'xxx', city: 'city', highConfidenceOnly: true, - mcc: 0, - phone: 0, + mcc: 'string', + phone: 'string', ); // @phpstan-ignore-next-line method.alreadyNarrowedType @@ -88,7 +89,7 @@ public function testRetrieveSimplified(): void $this->markTestSkipped('Mock server tests are disabled'); } - $result = $this->client->brand->retrieveSimplified(domain: 'domain'); + $result = $this->client->brand->retrieveSimplified(domain: 'xxx'); // @phpstan-ignore-next-line method.alreadyNarrowedType $this->assertInstanceOf(BrandGetSimplifiedResponse::class, $result); @@ -102,9 +103,11 @@ public function testRetrieveSimplifiedWithOptionalParams(): void } $result = $this->client->brand->retrieveSimplified( - domain: 'domain', - maxAgeMs: 86400000, - timeoutMs: 1000 + domain: 'xxx', + maxAgeMs: 0, + tags: ['production', 'team-alpha'], + theme: 'light', + timeoutMs: 1000, ); // @phpstan-ignore-next-line method.alreadyNarrowedType diff --git a/tests/Services/IndustryTest.php b/tests/Services/IndustryTest.php index 51c80f1..ad6fc72 100644 --- a/tests/Services/IndustryTest.php +++ b/tests/Services/IndustryTest.php @@ -36,7 +36,7 @@ public function testRetrieveNaics(): void $this->markTestSkipped('Mock server tests are disabled'); } - $result = $this->client->industry->retrieveNaics(input: 'input'); + $result = $this->client->industry->retrieveNaics(input: 'xxxx'); // @phpstan-ignore-next-line method.alreadyNarrowedType $this->assertInstanceOf(IndustryGetNaicsResponse::class, $result); @@ -50,10 +50,11 @@ public function testRetrieveNaicsWithOptionalParams(): void } $result = $this->client->industry->retrieveNaics( - input: 'input', + input: 'xxxx', maxResults: 1, minResults: 1, - timeoutMs: 1000 + tags: ['production', 'team-alpha'], + timeoutMs: 1000, ); // @phpstan-ignore-next-line method.alreadyNarrowedType @@ -67,7 +68,7 @@ public function testRetrieveSic(): void $this->markTestSkipped('Mock server tests are disabled'); } - $result = $this->client->industry->retrieveSic(input: 'input'); + $result = $this->client->industry->retrieveSic(input: 'xxxx'); // @phpstan-ignore-next-line method.alreadyNarrowedType $this->assertInstanceOf(IndustryGetSicResponse::class, $result); @@ -81,9 +82,10 @@ public function testRetrieveSicWithOptionalParams(): void } $result = $this->client->industry->retrieveSic( - input: 'input', + input: 'xxxx', maxResults: 1, minResults: 1, + tags: ['production', 'team-alpha'], timeoutMs: 1000, type: 'original_sic', ); diff --git a/tests/Services/UtilityTest.php b/tests/Services/UtilityTest.php index f59410a..474d4f0 100644 --- a/tests/Services/UtilityTest.php +++ b/tests/Services/UtilityTest.php @@ -36,7 +36,7 @@ public function testPrefetch(): void } $result = $this->client->utility->prefetch( - identifier: ['domain' => 'domain'], + identifier: ['domain' => 'xxx'], type: 'brand' ); @@ -52,9 +52,10 @@ public function testPrefetchWithOptionalParams(): void } $result = $this->client->utility->prefetch( - identifier: ['domain' => 'domain'], + identifier: ['domain' => 'xxx'], type: 'brand', - timeoutMs: 1000 + tags: ['production', 'team-alpha'], + timeoutMs: 1000, ); // @phpstan-ignore-next-line method.alreadyNarrowedType diff --git a/tests/Services/WebTest.php b/tests/Services/WebTest.php index f3044c8..598fa42 100644 --- a/tests/Services/WebTest.php +++ b/tests/Services/WebTest.php @@ -83,6 +83,7 @@ public function testExtractWithOptionalParams(): void maxPages: 1, pdf: ['end' => 1, 'shouldParse' => true, 'start' => 1], stopAfterMs: 10000, + tags: ['production', 'team-alpha'], timeoutMs: 1000, waitForMs: 0, ); @@ -114,7 +115,8 @@ public function testExtractCompetitorsWithOptionalParams(): void $result = $this->client->web->extractCompetitors( domain: 'xxx', numCompetitors: 1, - timeoutMs: 1000 + tags: ['production', 'team-alpha'], + timeoutMs: 1000, ); // @phpstan-ignore-next-line method.alreadyNarrowedType @@ -200,6 +202,7 @@ public function testSearchWithOptionalParams(): void ], numResults: 10, queryFanout: true, + tags: ['production', 'team-alpha'], timeoutMs: 1000, ); @@ -243,6 +246,7 @@ public function testWebCrawlMdWithOptionalParams(): void settleAnimations: true, shortenBase64Images: true, stopAfterMs: 10000, + tags: ['production', 'team-alpha'], timeoutMs: 1000, urlRegex: '^https?://[^/]+/blog/', useMainContentOnly: true, @@ -276,15 +280,16 @@ public function testWebScrapeHTMLWithOptionalParams(): void $result = $this->client->web->webScrapeHTML( url: 'https://example.com', country: 'de', - excludeSelectors: ['string'], + excludeSelectors: ['x'], headers: ['foo' => 'J!'], - includeFrames: true, - includeSelectors: ['string'], + includeFrames: 'true', + includeSelectors: ['x'], maxAgeMs: 0, - pdf: ['end' => 1, 'ocr' => true, 'shouldParse' => true, 'start' => 1], - settleAnimations: true, - timeoutMs: 1000, - useMainContentOnly: true, + pdf: ['end' => 1, 'ocr' => 'true', 'shouldParse' => 'true', 'start' => 1], + settleAnimations: 'true', + tags: ['production', 'team-alpha'], + timeoutMs: 1, + useMainContentOnly: 'true', waitForMs: 0, ); @@ -314,16 +319,17 @@ public function testWebScrapeImagesWithOptionalParams(): void $result = $this->client->web->webScrapeImages( url: 'https://example.com', - dedupe: true, + dedupe: 'true', enrichment: [ - 'classification' => true, - 'hostedURL' => true, + 'classification' => 'true', + 'hostedURL' => 'true', 'maxTimePerMs' => 1, - 'resolution' => true, + 'resolution' => 'true', ], headers: ['foo' => 'J!'], maxAgeMs: 0, - timeoutMs: 1000, + tags: ['production', 'team-alpha'], + timeoutMs: 1, waitForMs: 0, ); @@ -354,18 +360,19 @@ public function testWebScrapeMdWithOptionalParams(): void $result = $this->client->web->webScrapeMd( url: 'https://example.com', country: 'de', - excludeSelectors: ['string'], + excludeSelectors: ['x'], headers: ['foo' => 'J!'], - includeFrames: true, - includeImages: true, - includeLinks: true, - includeSelectors: ['string'], + includeFrames: 'true', + includeImages: 'true', + includeLinks: 'true', + includeSelectors: ['x'], maxAgeMs: 0, - pdf: ['end' => 1, 'ocr' => true, 'shouldParse' => true, 'start' => 1], - settleAnimations: true, - shortenBase64Images: true, - timeoutMs: 1000, - useMainContentOnly: true, + pdf: ['end' => 1, 'ocr' => 'true', 'shouldParse' => 'true', 'start' => 1], + settleAnimations: 'true', + shortenBase64Images: 'true', + tags: ['production', 'team-alpha'], + timeoutMs: 1, + useMainContentOnly: 'true', waitForMs: 0, ); @@ -380,7 +387,7 @@ public function testWebScrapeSitemap(): void $this->markTestSkipped('Mock server tests are disabled'); } - $result = $this->client->web->webScrapeSitemap(domain: 'domain'); + $result = $this->client->web->webScrapeSitemap(domain: 'xxx'); // @phpstan-ignore-next-line method.alreadyNarrowedType $this->assertInstanceOf(WebWebScrapeSitemapResponse::class, $result); @@ -394,10 +401,12 @@ public function testWebScrapeSitemapWithOptionalParams(): void } $result = $this->client->web->webScrapeSitemap( - domain: 'domain', + domain: 'xxx', headers: ['foo' => 'J!'], maxLinks: 1, - timeoutMs: 1000, + sitemapURL: 'https://example.com', + tags: ['production', 'team-alpha'], + timeoutMs: 1, urlRegex: '^https?://[^/]+/blog/', );