diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 243cf42..84d8fb1 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -18,7 +18,7 @@ jobs: lint: timeout-minutes: 10 name: lint - runs-on: ${{ github.repository == 'stainless-sdks/context.dev-php' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }} + runs-on: ${{ startsWith(github.repository, 'stainless-sdks/') && 'depot-ubuntu-24.04' || 'ubuntu-latest' }} if: github.event_name == 'push' || github.event.pull_request.head.repo.fork steps: @@ -37,7 +37,7 @@ jobs: test: timeout-minutes: 10 name: test - runs-on: ${{ github.repository == 'stainless-sdks/context.dev-php' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }} + runs-on: ${{ startsWith(github.repository, 'stainless-sdks/') && 'depot-ubuntu-24.04' || 'ubuntu-latest' }} if: github.event_name == 'push' || github.event.pull_request.head.repo.fork steps: - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 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..0ac1eb3 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 -config_hash: daabb160675d86b354711da1e77e5129 +configured_endpoints: 32 +openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/context-dev/context.dev-242450ea46eb8c3e843fd6c4bf87e73192b5f62f6da697cd091d13c6aa7a991b.yml +openapi_spec_hash: c1c561976de1abcacede71fd5ab9b3d9 +config_hash: 70e7e80b5e87f94981bee396c6cd41e8 diff --git a/CHANGELOG.md b/CHANGELOG.md index e0a0fd1..3a07e8d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,21 @@ # Changelog +## 2.5.0 (2026-07-22) + +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 ([010f4c0](https://github.com/context-dot-dev/context-php-sdk/commit/010f4c0c535137516b46f722b1d768422d4107b8)) +* **api:** api update ([b81393a](https://github.com/context-dot-dev/context-php-sdk/commit/b81393a0e2ad8b2e184555a4cbefff55c9f78085)) +* **api:** api update ([31e96ec](https://github.com/context-dot-dev/context-php-sdk/commit/31e96ec38f5746807e2d0bb2a58d5fee86e628c9)) +* **api:** api update ([c0beeca](https://github.com/context-dot-dev/context-php-sdk/commit/c0beecafa76546b693bc4fc21ba2a5d866c3a800)) +* **api:** api update ([4545026](https://github.com/context-dot-dev/context-php-sdk/commit/454502638c42c3f616a4b05182ccfadbedc4094e)) +* **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)) +* **api:** manual updates ([e6af5a4](https://github.com/context-dot-dev/context-php-sdk/commit/e6af5a4a974d252d12b03fa44e0e4258dd217412)) +* **stlc:** configurable CI runner and private-production-repo support in workflow templates ([ffd1499](https://github.com/context-dot-dev/context-php-sdk/commit/ffd14997114f4bfc701996334a6d39a479f17b2f)) + ## 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..821ff02 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 tags for tracking usage. Up to 20 tags, each 1 to 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 tags for tracking usage. Up to 20 tags, each 1 to 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..f6bb0b0 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 tags for tracking usage. Up to 20 tags, each 1 to 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 tags for tracking usage. Up to 20 tags, each 1 to 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..5ffa05d 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 tags for tracking usage. Up to 20 tags, each 1 to 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 tags for tracking usage. Up to 20 tags, each 1 to 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/MonitorCreateParams.php b/src/Monitors/MonitorCreateParams.php index 292b75b..56eec6e 100644 --- a/src/Monitors/MonitorCreateParams.php +++ b/src/Monitors/MonitorCreateParams.php @@ -82,7 +82,7 @@ final class MonitorCreateParams implements BaseModel public ?string $mode; /** - * User-defined tags for grouping and filtering monitors and their changes. + * User-defined tags for grouping and filtering monitors and their changes. Duplicates are removed. * * @var list|null $tags */ @@ -215,7 +215,7 @@ public function withMode(Mode|string $mode): self } /** - * User-defined tags for grouping and filtering monitors and their changes. + * User-defined tags for grouping and filtering monitors and their changes. Duplicates are removed. * * @param list $tags */ diff --git a/src/Monitors/MonitorCreateParams/Target/MonitorsSitemapTarget.php b/src/Monitors/MonitorCreateParams/Target/MonitorsSitemapTarget.php index a16f418..4ec7ff1 100644 --- a/src/Monitors/MonitorCreateParams/Target/MonitorsSitemapTarget.php +++ b/src/Monitors/MonitorCreateParams/Target/MonitorsSitemapTarget.php @@ -36,7 +36,7 @@ final class MonitorsSitemapTarget implements BaseModel public string $url; /** - * URL path patterns to exclude. + * URL path patterns to exclude (max 50). * * @var list|null $exclude */ @@ -44,7 +44,7 @@ final class MonitorsSitemapTarget implements BaseModel public ?array $exclude; /** - * URL path patterns to include. + * URL path patterns to include (max 50). * * @var list|null $include */ @@ -124,7 +124,7 @@ public function withURL(string $url): self } /** - * URL path patterns to exclude. + * URL path patterns to exclude (max 50). * * @param list $exclude */ @@ -137,7 +137,7 @@ public function withExclude(array $exclude): self } /** - * URL path patterns to include. + * URL path patterns to include (max 50). * * @param list $include */ diff --git a/src/Monitors/MonitorGetChangeResponse.php b/src/Monitors/MonitorGetChangeResponse.php index a73cf03..f36d5fe 100644 --- a/src/Monitors/MonitorGetChangeResponse.php +++ b/src/Monitors/MonitorGetChangeResponse.php @@ -81,7 +81,7 @@ final class MonitorGetChangeResponse implements BaseModel public string $summary; /** - * User-defined tags for grouping and filtering monitors and their changes. + * User-defined tags for grouping and filtering monitors and their changes. Duplicates are removed. * * @var list $tags */ @@ -335,7 +335,7 @@ public function withSummary(string $summary): self } /** - * User-defined tags for grouping and filtering monitors and their changes. + * User-defined tags for grouping and filtering monitors and their changes. Duplicates are removed. * * @param list $tags */ diff --git a/src/Monitors/MonitorGetCreditUsageParams.php b/src/Monitors/MonitorGetCreditUsageParams.php new file mode 100644 index 0000000..d1f5148 --- /dev/null +++ b/src/Monitors/MonitorGetCreditUsageParams.php @@ -0,0 +1,82 @@ + */ + use SdkModel; + use SdkParams; + + /** + * Only include items at or after this ISO 8601 timestamp. + */ + #[Optional] + public ?\DateTimeInterface $since; + + /** + * Only include items before this ISO 8601 timestamp. + */ + #[Optional] + public ?\DateTimeInterface $until; + + 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( + ?\DateTimeInterface $since = null, + ?\DateTimeInterface $until = null + ): self { + $self = new self; + + null !== $since && $self['since'] = $since; + null !== $until && $self['until'] = $until; + + return $self; + } + + /** + * Only include items at or after this ISO 8601 timestamp. + */ + public function withSince(\DateTimeInterface $since): self + { + $self = clone $this; + $self['since'] = $since; + + return $self; + } + + /** + * Only include items before this ISO 8601 timestamp. + */ + public function withUntil(\DateTimeInterface $until): self + { + $self = clone $this; + $self['until'] = $until; + + return $self; + } +} diff --git a/src/Monitors/MonitorGetCreditUsageResponse.php b/src/Monitors/MonitorGetCreditUsageResponse.php new file mode 100644 index 0000000..2d10354 --- /dev/null +++ b/src/Monitors/MonitorGetCreditUsageResponse.php @@ -0,0 +1,91 @@ +, totalCredits: int + * } + */ +final class MonitorGetCreditUsageResponse implements BaseModel +{ + /** @use SdkModel */ + use SdkModel; + + /** @var list $data */ + #[Required(list: Data::class)] + public array $data; + + /** + * Sum of credits across all monitors in the window. + */ + #[Required('total_credits')] + public int $totalCredits; + + /** + * `new MonitorGetCreditUsageResponse()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * MonitorGetCreditUsageResponse::with(data: ..., totalCredits: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new MonitorGetCreditUsageResponse)->withData(...)->withTotalCredits(...) + * ``` + */ + 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 list $data + */ + public static function with(array $data, int $totalCredits): self + { + $self = new self; + + $self['data'] = $data; + $self['totalCredits'] = $totalCredits; + + return $self; + } + + /** + * @param list $data + */ + public function withData(array $data): self + { + $self = clone $this; + $self['data'] = $data; + + return $self; + } + + /** + * Sum of credits across all monitors in the window. + */ + public function withTotalCredits(int $totalCredits): self + { + $self = clone $this; + $self['totalCredits'] = $totalCredits; + + return $self; + } +} diff --git a/src/Monitors/MonitorGetCreditUsageResponse/Data.php b/src/Monitors/MonitorGetCreditUsageResponse/Data.php new file mode 100644 index 0000000..2cc39bb --- /dev/null +++ b/src/Monitors/MonitorGetCreditUsageResponse/Data.php @@ -0,0 +1,122 @@ + */ + use SdkModel; + + /** + * Credits charged to this monitor over the window. + */ + #[Required] + public int $credits; + + #[Required('monitor_id')] + public string $monitorID; + + /** + * Monitor name (falls back to the id when the monitor was deleted). + */ + #[Required] + public string $name; + + /** + * Number of billed runs over the window. + */ + #[Required] + public int $runs; + + /** + * `new Data()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * Data::with(credits: ..., monitorID: ..., name: ..., runs: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new Data)->withCredits(...)->withMonitorID(...)->withName(...)->withRuns(...) + * ``` + */ + public function __construct() + { + $this->initialize(); + } + + /** + * Construct an instance from the required parameters. + * + * You must use named parameters to construct any parameters with a default value. + */ + public static function with( + int $credits, + string $monitorID, + string $name, + int $runs + ): self { + $self = new self; + + $self['credits'] = $credits; + $self['monitorID'] = $monitorID; + $self['name'] = $name; + $self['runs'] = $runs; + + return $self; + } + + /** + * Credits charged to this monitor over the window. + */ + public function withCredits(int $credits): self + { + $self = clone $this; + $self['credits'] = $credits; + + return $self; + } + + public function withMonitorID(string $monitorID): self + { + $self = clone $this; + $self['monitorID'] = $monitorID; + + return $self; + } + + /** + * Monitor name (falls back to the id when the monitor was deleted). + */ + public function withName(string $name): self + { + $self = clone $this; + $self['name'] = $name; + + return $self; + } + + /** + * Number of billed runs over the window. + */ + public function withRuns(int $runs): self + { + $self = clone $this; + $self['runs'] = $runs; + + return $self; + } +} diff --git a/src/Monitors/MonitorGetLimitsResponse.php b/src/Monitors/MonitorGetLimitsResponse.php new file mode 100644 index 0000000..e8e692e --- /dev/null +++ b/src/Monitors/MonitorGetLimitsResponse.php @@ -0,0 +1,119 @@ + + * } + */ +final class MonitorGetLimitsResponse implements BaseModel +{ + /** @use SdkModel */ + use SdkModel; + + /** + * Maximum number of monitors allowed for the account. Defaults to the plan allowance unless a custom limit is set for the organization. + */ + #[Required('monitors_limit')] + public int $monitorsLimit; + + /** + * Number of monitors the account currently has. + */ + #[Required('monitors_used')] + public int $monitorsUsed; + + /** + * The plan tier the limit was resolved from. + * + * @var value-of $plan + */ + #[Required(enum: Plan::class)] + public string $plan; + + /** + * `new MonitorGetLimitsResponse()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * MonitorGetLimitsResponse::with(monitorsLimit: ..., monitorsUsed: ..., plan: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new MonitorGetLimitsResponse) + * ->withMonitorsLimit(...) + * ->withMonitorsUsed(...) + * ->withPlan(...) + * ``` + */ + 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 Plan|value-of $plan + */ + public static function with( + int $monitorsLimit, + int $monitorsUsed, + Plan|string $plan + ): self { + $self = new self; + + $self['monitorsLimit'] = $monitorsLimit; + $self['monitorsUsed'] = $monitorsUsed; + $self['plan'] = $plan; + + return $self; + } + + /** + * Maximum number of monitors allowed for the account. Defaults to the plan allowance unless a custom limit is set for the organization. + */ + public function withMonitorsLimit(int $monitorsLimit): self + { + $self = clone $this; + $self['monitorsLimit'] = $monitorsLimit; + + return $self; + } + + /** + * Number of monitors the account currently has. + */ + public function withMonitorsUsed(int $monitorsUsed): self + { + $self = clone $this; + $self['monitorsUsed'] = $monitorsUsed; + + return $self; + } + + /** + * The plan tier the limit was resolved from. + * + * @param Plan|value-of $plan + */ + public function withPlan(Plan|string $plan): self + { + $self = clone $this; + $self['plan'] = $plan; + + return $self; + } +} diff --git a/src/Monitors/MonitorGetLimitsResponse/Plan.php b/src/Monitors/MonitorGetLimitsResponse/Plan.php new file mode 100644 index 0000000..9b23fe3 --- /dev/null +++ b/src/Monitors/MonitorGetLimitsResponse/Plan.php @@ -0,0 +1,19 @@ +|null $tags */ @@ -408,7 +408,7 @@ public function withNextRunAt(?\DateTimeInterface $nextRunAt): self } /** - * User-defined tags for grouping and filtering monitors and their changes. + * User-defined tags for grouping and filtering monitors and their changes. Duplicates are removed. * * @param list $tags */ diff --git a/src/Monitors/MonitorGetResponse/Target/MonitorsSitemapTarget.php b/src/Monitors/MonitorGetResponse/Target/MonitorsSitemapTarget.php index 28ee9ec..3d10355 100644 --- a/src/Monitors/MonitorGetResponse/Target/MonitorsSitemapTarget.php +++ b/src/Monitors/MonitorGetResponse/Target/MonitorsSitemapTarget.php @@ -36,7 +36,7 @@ final class MonitorsSitemapTarget implements BaseModel public string $url; /** - * URL path patterns to exclude. + * URL path patterns to exclude (max 50). * * @var list|null $exclude */ @@ -44,7 +44,7 @@ final class MonitorsSitemapTarget implements BaseModel public ?array $exclude; /** - * URL path patterns to include. + * URL path patterns to include (max 50). * * @var list|null $include */ @@ -124,7 +124,7 @@ public function withURL(string $url): self } /** - * URL path patterns to exclude. + * URL path patterns to exclude (max 50). * * @param list $exclude */ @@ -137,7 +137,7 @@ public function withExclude(array $exclude): self } /** - * URL path patterns to include. + * URL path patterns to include (max 50). * * @param list $include */ 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/MonitorListAccountChangesResponse/Data.php b/src/Monitors/MonitorListAccountChangesResponse/Data.php index 9d2a560..26bde44 100644 --- a/src/Monitors/MonitorListAccountChangesResponse/Data.php +++ b/src/Monitors/MonitorListAccountChangesResponse/Data.php @@ -90,7 +90,7 @@ final class Data implements BaseModel public ?int $removedURLCount; /** - * User-defined tags for grouping and filtering monitors and their changes. + * User-defined tags for grouping and filtering monitors and their changes. Duplicates are removed. * * @var list|null $tags */ @@ -313,7 +313,7 @@ public function withRemovedURLCount(int $removedURLCount): self } /** - * User-defined tags for grouping and filtering monitors and their changes. + * User-defined tags for grouping and filtering monitors and their changes. Duplicates are removed. * * @param list $tags */ 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/MonitorListChangesParams.php b/src/Monitors/MonitorListChangesParams.php index 213cba9..ecb93d7 100644 --- a/src/Monitors/MonitorListChangesParams.php +++ b/src/Monitors/MonitorListChangesParams.php @@ -28,12 +28,21 @@ final class MonitorListChangesParams 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; + /** + * Only include items at or after this ISO 8601 timestamp. + */ #[Optional] public ?\DateTimeInterface $since; @@ -43,6 +52,9 @@ final class MonitorListChangesParams implements BaseModel #[Optional] public ?string $tag; + /** + * Only include items before this ISO 8601 timestamp. + */ #[Optional] public ?\DateTimeInterface $until; @@ -74,6 +86,9 @@ public static function with( return $self; } + /** + * Opaque pagination cursor from a previous response. + */ public function withCursor(string $cursor): self { $self = clone $this; @@ -82,6 +97,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; @@ -90,6 +108,9 @@ public function withLimit(int $limit): self return $self; } + /** + * Only include items at or after this ISO 8601 timestamp. + */ public function withSince(\DateTimeInterface $since): self { $self = clone $this; @@ -109,6 +130,9 @@ public function withTag(string $tag): 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/MonitorListChangesResponse/Data.php b/src/Monitors/MonitorListChangesResponse/Data.php index cf01a7a..d52716e 100644 --- a/src/Monitors/MonitorListChangesResponse/Data.php +++ b/src/Monitors/MonitorListChangesResponse/Data.php @@ -90,7 +90,7 @@ final class Data implements BaseModel public ?int $removedURLCount; /** - * User-defined tags for grouping and filtering monitors and their changes. + * User-defined tags for grouping and filtering monitors and their changes. Duplicates are removed. * * @var list|null $tags */ @@ -313,7 +313,7 @@ public function withRemovedURLCount(int $removedURLCount): self } /** - * User-defined tags for grouping and filtering monitors and their changes. + * User-defined tags for grouping and filtering monitors and their changes. Duplicates are removed. * * @param list $tags */ diff --git a/src/Monitors/MonitorListParams.php b/src/Monitors/MonitorListParams.php index 2119e05..6478a97 100644 --- a/src/Monitors/MonitorListParams.php +++ b/src/Monitors/MonitorListParams.php @@ -38,13 +38,23 @@ final class MonitorListParams 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; @@ -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/MonitorListResponse/Data.php b/src/Monitors/MonitorListResponse/Data.php index ce0be23..ceffa40 100644 --- a/src/Monitors/MonitorListResponse/Data.php +++ b/src/Monitors/MonitorListResponse/Data.php @@ -141,7 +141,7 @@ final class Data implements BaseModel public ?\DateTimeInterface $nextRunAt; /** - * User-defined tags for grouping and filtering monitors and their changes. + * User-defined tags for grouping and filtering monitors and their changes. Duplicates are removed. * * @var list|null $tags */ @@ -408,7 +408,7 @@ public function withNextRunAt(?\DateTimeInterface $nextRunAt): self } /** - * User-defined tags for grouping and filtering monitors and their changes. + * User-defined tags for grouping and filtering monitors and their changes. Duplicates are removed. * * @param list $tags */ diff --git a/src/Monitors/MonitorListResponse/Data/Target/MonitorsSitemapTarget.php b/src/Monitors/MonitorListResponse/Data/Target/MonitorsSitemapTarget.php index b16de60..f14d6a7 100644 --- a/src/Monitors/MonitorListResponse/Data/Target/MonitorsSitemapTarget.php +++ b/src/Monitors/MonitorListResponse/Data/Target/MonitorsSitemapTarget.php @@ -36,7 +36,7 @@ final class MonitorsSitemapTarget implements BaseModel public string $url; /** - * URL path patterns to exclude. + * URL path patterns to exclude (max 50). * * @var list|null $exclude */ @@ -44,7 +44,7 @@ final class MonitorsSitemapTarget implements BaseModel public ?array $exclude; /** - * URL path patterns to include. + * URL path patterns to include (max 50). * * @var list|null $include */ @@ -124,7 +124,7 @@ public function withURL(string $url): self } /** - * URL path patterns to exclude. + * URL path patterns to exclude (max 50). * * @param list $exclude */ @@ -137,7 +137,7 @@ public function withExclude(array $exclude): self } /** - * URL path patterns to include. + * URL path patterns to include (max 50). * * @param list $include */ 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/MonitorNewResponse.php b/src/Monitors/MonitorNewResponse.php index 8cbef5f..d70d44e 100644 --- a/src/Monitors/MonitorNewResponse.php +++ b/src/Monitors/MonitorNewResponse.php @@ -141,7 +141,7 @@ final class MonitorNewResponse implements BaseModel public ?\DateTimeInterface $nextRunAt; /** - * User-defined tags for grouping and filtering monitors and their changes. + * User-defined tags for grouping and filtering monitors and their changes. Duplicates are removed. * * @var list|null $tags */ @@ -408,7 +408,7 @@ public function withNextRunAt(?\DateTimeInterface $nextRunAt): self } /** - * User-defined tags for grouping and filtering monitors and their changes. + * User-defined tags for grouping and filtering monitors and their changes. Duplicates are removed. * * @param list $tags */ diff --git a/src/Monitors/MonitorNewResponse/Target/MonitorsSitemapTarget.php b/src/Monitors/MonitorNewResponse/Target/MonitorsSitemapTarget.php index f01e31b..6ac56c8 100644 --- a/src/Monitors/MonitorNewResponse/Target/MonitorsSitemapTarget.php +++ b/src/Monitors/MonitorNewResponse/Target/MonitorsSitemapTarget.php @@ -36,7 +36,7 @@ final class MonitorsSitemapTarget implements BaseModel public string $url; /** - * URL path patterns to exclude. + * URL path patterns to exclude (max 50). * * @var list|null $exclude */ @@ -44,7 +44,7 @@ final class MonitorsSitemapTarget implements BaseModel public ?array $exclude; /** - * URL path patterns to include. + * URL path patterns to include (max 50). * * @var list|null $include */ @@ -124,7 +124,7 @@ public function withURL(string $url): self } /** - * URL path patterns to exclude. + * URL path patterns to exclude (max 50). * * @param list $exclude */ @@ -137,7 +137,7 @@ public function withExclude(array $exclude): self } /** - * URL path patterns to include. + * URL path patterns to include (max 50). * * @param list $include */ diff --git a/src/Monitors/MonitorUpdateParams.php b/src/Monitors/MonitorUpdateParams.php index 606b67c..472d6e2 100644 --- a/src/Monitors/MonitorUpdateParams.php +++ b/src/Monitors/MonitorUpdateParams.php @@ -69,7 +69,7 @@ final class MonitorUpdateParams implements BaseModel public ?string $status; /** - * User-defined tags for grouping and filtering monitors and their changes. + * User-defined tags for grouping and filtering monitors and their changes. Duplicates are removed. * * @var list|null $tags */ @@ -176,7 +176,7 @@ public function withStatus(Status|string $status): self } /** - * User-defined tags for grouping and filtering monitors and their changes. + * User-defined tags for grouping and filtering monitors and their changes. Duplicates are removed. * * @param list $tags */ diff --git a/src/Monitors/MonitorUpdateParams/Target/MonitorsSitemapTarget.php b/src/Monitors/MonitorUpdateParams/Target/MonitorsSitemapTarget.php index 5da0cb2..2b002b1 100644 --- a/src/Monitors/MonitorUpdateParams/Target/MonitorsSitemapTarget.php +++ b/src/Monitors/MonitorUpdateParams/Target/MonitorsSitemapTarget.php @@ -36,7 +36,7 @@ final class MonitorsSitemapTarget implements BaseModel public string $url; /** - * URL path patterns to exclude. + * URL path patterns to exclude (max 50). * * @var list|null $exclude */ @@ -44,7 +44,7 @@ final class MonitorsSitemapTarget implements BaseModel public ?array $exclude; /** - * URL path patterns to include. + * URL path patterns to include (max 50). * * @var list|null $include */ @@ -124,7 +124,7 @@ public function withURL(string $url): self } /** - * URL path patterns to exclude. + * URL path patterns to exclude (max 50). * * @param list $exclude */ @@ -137,7 +137,7 @@ public function withExclude(array $exclude): self } /** - * URL path patterns to include. + * URL path patterns to include (max 50). * * @param list $include */ diff --git a/src/Monitors/MonitorUpdateResponse.php b/src/Monitors/MonitorUpdateResponse.php index 885d686..4e9b8a5 100644 --- a/src/Monitors/MonitorUpdateResponse.php +++ b/src/Monitors/MonitorUpdateResponse.php @@ -141,7 +141,7 @@ final class MonitorUpdateResponse implements BaseModel public ?\DateTimeInterface $nextRunAt; /** - * User-defined tags for grouping and filtering monitors and their changes. + * User-defined tags for grouping and filtering monitors and their changes. Duplicates are removed. * * @var list|null $tags */ @@ -408,7 +408,7 @@ public function withNextRunAt(?\DateTimeInterface $nextRunAt): self } /** - * User-defined tags for grouping and filtering monitors and their changes. + * User-defined tags for grouping and filtering monitors and their changes. Duplicates are removed. * * @param list $tags */ diff --git a/src/Monitors/MonitorUpdateResponse/Target/MonitorsSitemapTarget.php b/src/Monitors/MonitorUpdateResponse/Target/MonitorsSitemapTarget.php index 28a9b2f..2df7fc1 100644 --- a/src/Monitors/MonitorUpdateResponse/Target/MonitorsSitemapTarget.php +++ b/src/Monitors/MonitorUpdateResponse/Target/MonitorsSitemapTarget.php @@ -36,7 +36,7 @@ final class MonitorsSitemapTarget implements BaseModel public string $url; /** - * URL path patterns to exclude. + * URL path patterns to exclude (max 50). * * @var list|null $exclude */ @@ -44,7 +44,7 @@ final class MonitorsSitemapTarget implements BaseModel public ?array $exclude; /** - * URL path patterns to include. + * URL path patterns to include (max 50). * * @var list|null $include */ @@ -124,7 +124,7 @@ public function withURL(string $url): self } /** - * URL path patterns to exclude. + * URL path patterns to exclude (max 50). * * @param list $exclude */ @@ -137,7 +137,7 @@ public function withExclude(array $exclude): self } /** - * URL path patterns to include. + * URL path patterns to include (max 50). * * @param list $include */ diff --git a/src/Parse/ParseHandleParams.php b/src/Parse/ParseHandleParams.php index ca29954..7e18b75 100644 --- a/src/Parse/ParseHandleParams.php +++ b/src/Parse/ParseHandleParams.php @@ -9,23 +9,43 @@ use ContextDev\Core\Concerns\SdkParams; use ContextDev\Core\Contracts\BaseModel; use ContextDev\Parse\ParseHandleParams\Extension; +use ContextDev\Parse\ParseHandleParams\IncludeImages; +use ContextDev\Parse\ParseHandleParams\IncludeImages\UnionMember1; +use ContextDev\Parse\ParseHandleParams\IncludeLinks; +use ContextDev\Parse\ParseHandleParams\Ocr; use ContextDev\Parse\ParseHandleParams\Pdf; +use ContextDev\Parse\ParseHandleParams\ShortenBase64Images; +use ContextDev\Parse\ParseHandleParams\UseMainContentOnly; +use ContextDev\Parse\ParseHandleParams\Zdr; /** - * 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. * * @see ContextDev\Services\ParseService::handle() * + * @phpstan-import-type IncludeImagesVariants from \ContextDev\Parse\ParseHandleParams\IncludeImages + * @phpstan-import-type IncludeLinksVariants from \ContextDev\Parse\ParseHandleParams\IncludeLinks + * @phpstan-import-type OcrVariants from \ContextDev\Parse\ParseHandleParams\Ocr + * @phpstan-import-type ShortenBase64ImagesVariants from \ContextDev\Parse\ParseHandleParams\ShortenBase64Images + * @phpstan-import-type UseMainContentOnlyVariants from \ContextDev\Parse\ParseHandleParams\UseMainContentOnly + * @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-type ParseHandleParamsShape = array{ + * client?: string|null, * extension?: null|Extension|value-of, - * 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, + * zdr?: null|Zdr|value-of, * } */ final class ParseHandleParams implements BaseModel @@ -35,7 +55,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 +70,65 @@ 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; + + /** + * Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true. + * + * @var value-of|null $zdr + */ + #[Optional(enum: Zdr::class)] + public ?string $zdr; public function __construct() { @@ -89,32 +141,56 @@ 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 + * @param Zdr|value-of|null $zdr */ 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, + Zdr|string|null $zdr = 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; + null !== $zdr && $self['zdr'] = $zdr; + + return $self; + } + + /** + * 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. 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. * * @param Extension|value-of $extension */ @@ -128,9 +204,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 +218,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 +231,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 +245,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 +259,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,13 +272,42 @@ 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; return $self; } + + /** + * Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true. + * + * @param Zdr|value-of $zdr + */ + public function withZdr(Zdr|string $zdr): self + { + $self = clone $this; + $self['zdr'] = $zdr; + + return $self; + } } 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 tags for tracking usage. Up to 20 tags, each 1 to 50 characters. * @param int $timeoutMs Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes). * @param RequestOpts|null $requestOptions * @@ -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 tags for tracking usage. Up to 20 tags, each 1 to 50 characters. * @param int $timeoutMs Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes). * @param RequestOpts|null $requestOptions * @@ -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..ce818d8 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 tags for tracking usage. Up to 20 tags, each 1 to 50 characters. * @param int $timeoutMs Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes). * @param 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..6a3ae2e 100644 --- a/src/ServiceContracts/MonitorsContract.php +++ b/src/ServiceContracts/MonitorsContract.php @@ -15,6 +15,8 @@ use ContextDev\Monitors\MonitorCreateParams\Webhook; use ContextDev\Monitors\MonitorDeleteResponse; use ContextDev\Monitors\MonitorGetChangeResponse; +use ContextDev\Monitors\MonitorGetCreditUsageResponse; +use ContextDev\Monitors\MonitorGetLimitsResponse; use ContextDev\Monitors\MonitorGetResponse; use ContextDev\Monitors\MonitorListAccountChangesResponse; use ContextDev\Monitors\MonitorListAccountRunsResponse; @@ -51,7 +53,7 @@ interface MonitorsContract * @param Schedule|ScheduleShape $schedule Run the monitor on a fixed interval defined by a frequency and a unit, e.g. every 6 hours or every 2 days. The total interval (frequency × unit) must be between 10 minutes and 1 year. * @param TargetShape $target discriminated union describing what the monitor watches * @param Mode|value-of $mode Top-level monitor category. Always `web` today; the concrete behavior is described by `target` and `change_detection`. - * @param list $tags user-defined tags for grouping and filtering monitors and their changes + * @param list $tags User-defined tags for grouping and filtering monitors and their changes. Duplicates are removed. * @param Webhook|WebhookShape|null $webhook * @param RequestOpts|null $requestOptions * @@ -86,7 +88,7 @@ public function retrieve( * @param ChangeDetectionShape1 $changeDetection discriminated union describing how changes are detected * @param \ContextDev\Monitors\MonitorUpdateParams\Schedule|ScheduleShape1 $schedule Run the monitor on a fixed interval defined by a frequency and a unit, e.g. every 6 hours or every 2 days. The total interval (frequency × unit) must be between 10 minutes and 1 year. * @param Status|value-of $status - * @param list $tags user-defined tags for grouping and filtering monitors and their changes + * @param list $tags User-defined tags for grouping and filtering monitors and their changes. Duplicates are removed. * @param TargetShape1 $target discriminated union describing what the monitor watches * @param \ContextDev\Monitors\MonitorUpdateParams\Webhook|WebhookShape1|null $webhook set to null to remove the webhook * @param RequestOpts|null $requestOptions @@ -108,14 +110,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 +127,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 +153,40 @@ public function delete( /** * @api * - * @param \ContextDev\Monitors\MonitorListAccountChangesParams\ChangeDetectionType|value-of<\ContextDev\Monitors\MonitorListAccountChangesParams\ChangeDetectionType> $changeDetectionType + * @param \DateTimeInterface $since only include items at or after this ISO 8601 timestamp + * @param \DateTimeInterface $until only include items before this ISO 8601 timestamp + * @param RequestOpts|null $requestOptions + * + * @throws APIException + */ + public function getCreditUsage( + ?\DateTimeInterface $since = null, + ?\DateTimeInterface $until = null, + RequestOptions|array|null $requestOptions = null, + ): MonitorGetCreditUsageResponse; + + /** + * @api + * + * @param RequestOpts|null $requestOptions + * + * @throws APIException + */ + public function getLimits( + RequestOptions|array|null $requestOptions = null + ): MonitorGetLimitsResponse; + + /** + * @api + * + * @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 +194,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 +206,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 +223,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 +235,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 +245,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 +255,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/MonitorsRawContract.php b/src/ServiceContracts/MonitorsRawContract.php index aad01ad..2c8f1ec 100644 --- a/src/ServiceContracts/MonitorsRawContract.php +++ b/src/ServiceContracts/MonitorsRawContract.php @@ -9,6 +9,9 @@ use ContextDev\Monitors\MonitorCreateParams; use ContextDev\Monitors\MonitorDeleteResponse; use ContextDev\Monitors\MonitorGetChangeResponse; +use ContextDev\Monitors\MonitorGetCreditUsageParams; +use ContextDev\Monitors\MonitorGetCreditUsageResponse; +use ContextDev\Monitors\MonitorGetLimitsResponse; use ContextDev\Monitors\MonitorGetResponse; use ContextDev\Monitors\MonitorListAccountChangesParams; use ContextDev\Monitors\MonitorListAccountChangesResponse; @@ -105,6 +108,34 @@ public function delete( RequestOptions|array|null $requestOptions = null ): BaseResponse; + /** + * @api + * + * @param array|MonitorGetCreditUsageParams $params + * @param RequestOpts|null $requestOptions + * + * @return BaseResponse + * + * @throws APIException + */ + public function getCreditUsage( + array|MonitorGetCreditUsageParams $params, + RequestOptions|array|null $requestOptions = null, + ): BaseResponse; + + /** + * @api + * + * @param RequestOpts|null $requestOptions + * + * @return BaseResponse + * + * @throws APIException + */ + public function getLimits( + RequestOptions|array|null $requestOptions = null + ): BaseResponse; + /** * @api * diff --git a/src/ServiceContracts/ParseContract.php b/src/ServiceContracts/ParseContract.php index e6ca67b..c724b43 100644 --- a/src/ServiceContracts/ParseContract.php +++ b/src/ServiceContracts/ParseContract.php @@ -7,12 +7,19 @@ 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\ParseHandleParams\Zdr; 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 +28,32 @@ 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 Zdr|value-of $zdr Query param: Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true. * @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, + Zdr|string $zdr = 'disabled', RequestOptions|array|null $requestOptions = null, ): ParseHandleResponse; } diff --git a/src/ServiceContracts/UtilityContract.php b/src/ServiceContracts/UtilityContract.php index 64ca1ad..eebf6f1 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 tags for tracking usage. Up to 20 tags, each 1 to 50 characters. * @param int $timeoutMs Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes). * @param RequestOpts|null $requestOptions * @@ -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..42edb5d 100644 --- a/src/ServiceContracts/WebContract.php +++ b/src/ServiceContracts/WebContract.php @@ -14,9 +14,10 @@ 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\WebScreenshotParams\Zdr; use ContextDev\Web\WebScreenshotResponse; use ContextDev\Web\WebSearchParams\Freshness; use ContextDev\Web\WebSearchParams\MarkdownOptions; @@ -30,12 +31,26 @@ /** * @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 ActionShape from \ContextDev\Web\WebWebScrapeHTMLParams\Action + * @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 ActionShape from \ContextDev\Web\WebWebScrapeImagesParams\Action as ActionShape1 + * @phpstan-import-type DedupeShape from \ContextDev\Web\WebWebScrapeImagesParams\Dedupe * @phpstan-import-type EnrichmentShape from \ContextDev\Web\WebWebScrapeImagesParams\Enrichment + * @phpstan-import-type ActionShape from \ContextDev\Web\WebWebScrapeMdParams\Action as ActionShape2 + * @phpstan-import-type IncludeFramesShape from \ContextDev\Web\WebWebScrapeMdParams\IncludeFrames as IncludeFramesShape1 + * @phpstan-import-type 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 @@ -53,7 +68,9 @@ interface WebContract * @param int $maxDepth Optional maximum link depth from the starting URL (0 = only the starting page). If omitted, there is no crawl depth limit. * @param int $maxPages Maximum number of pages to analyze for extraction. Hard cap: 50. Defaults to 5. * @param Pdf|PdfShape $pdf + * @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 int $stopAfterMs Soft time budget for the crawl in milliseconds. Min: 10000 (10s). Max: 110000 (110s). Default: 80000 (80s). + * @param list $tags Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. * @param int $timeoutMs Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes). * @param int $waitForMs optional browser wait time in milliseconds after initial page load for each crawled page * @param RequestOpts|null $requestOptions @@ -71,7 +88,9 @@ public function extract( ?int $maxDepth = null, int $maxPages = 5, Pdf|array $pdf = ['shouldParse' => true], + bool $settleAnimations = false, int $stopAfterMs = 80000, + ?array $tags = null, ?int $timeoutMs = null, ?int $waitForMs = null, RequestOptions|array|null $requestOptions = null, @@ -82,6 +101,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 +110,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 +120,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 +130,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 +142,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 +153,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 +163,19 @@ 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 Zdr|value-of $zdr Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true. * @param RequestOpts|null $requestOptions * * @throws APIException @@ -159,13 +186,15 @@ 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, + Zdr|string $zdr = 'disabled', RequestOptions|array|null $requestOptions = null, ): WebScreenshotResponse; @@ -180,6 +209,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 tags for tracking usage. Up to 20 tags, each 1 to 50 characters. * @param int $timeoutMs Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes). * @param RequestOpts|null $requestOptions * @@ -194,6 +224,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,10 +247,12 @@ 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 tags for tracking usage. Up to 20 tags, each 1 to 50 characters. * @param int $timeoutMs Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes). * @param 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 * @param int $waitForMs Optional browser wait time in milliseconds after initial page load for each crawled page. Min: 0. Max: 30000 (30 seconds). + * @param \ContextDev\Web\WebWebCrawlMdParams\Zdr|value-of<\ContextDev\Web\WebWebCrawlMdParams\Zdr> $zdr Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true. * @param RequestOpts|null $requestOptions * * @throws APIException @@ -242,10 +275,12 @@ public function webCrawlMd( bool $settleAnimations = false, bool $shortenBase64Images = true, int $stopAfterMs = 80000, + ?array $tags = null, ?int $timeoutMs = null, ?string $urlRegex = null, bool $useMainContentOnly = false, ?int $waitForMs = null, + \ContextDev\Web\WebWebCrawlMdParams\Zdr|string $zdr = 'disabled', RequestOptions|array|null $requestOptions = null, ): WebWebCrawlMdResponse; @@ -253,36 +288,42 @@ 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 list|null $actions Optional browser actions executed in array order after the page loads and before content is captured. Requires a paid plan. Send a JSON array in the query parameter. Maximum: 5 actions. + * @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 \ContextDev\Web\WebWebScrapeHTMLParams\Zdr|value-of<\ContextDev\Web\WebWebScrapeHTMLParams\Zdr> $zdr Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true. * @param RequestOpts|null $requestOptions * * @throws APIException */ public function webScrapeHTML( string $url, + ?array $actions = null, \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, + \ContextDev\Web\WebWebScrapeHTMLParams\Zdr|string $zdr = 'disabled', RequestOptions|array|null $requestOptions = null, ): WebWebScrapeHTMLResponse; @@ -290,22 +331,26 @@ 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 list|null $actions Optional browser actions executed in array order after the page loads and before content is captured. Requires a paid plan. Send a JSON array in the query parameter. Maximum: 5 actions. + * @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, + ?array $actions = null, + 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,42 +360,48 @@ 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 list|null $actions Optional browser actions executed in array order after the page loads and before content is captured. Requires a paid plan. Send a JSON array in the query parameter. Maximum: 5 actions. + * @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 \ContextDev\Web\WebWebScrapeMdParams\Zdr|value-of<\ContextDev\Web\WebWebScrapeMdParams\Zdr> $zdr Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true. * @param RequestOpts|null $requestOptions * * @throws APIException */ public function webScrapeMd( string $url, + ?array $actions = null, \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, + \ContextDev\Web\WebWebScrapeMdParams\Zdr|string $zdr = 'disabled', RequestOptions|array|null $requestOptions = null, ): WebWebScrapeMdResponse; @@ -360,8 +411,11 @@ 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 \ContextDev\Web\WebWebScrapeSitemapParams\Zdr|value-of<\ContextDev\Web\WebWebScrapeSitemapParams\Zdr> $zdr Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true. * @param RequestOpts|null $requestOptions * * @throws APIException @@ -370,8 +424,11 @@ public function webScrapeSitemap( string $domain, ?array $headers = null, int $maxLinks = 10000, + ?string $sitemapURL = null, + ?array $tags = null, ?int $timeoutMs = null, ?string $urlRegex = null, + \ContextDev\Web\WebWebScrapeSitemapParams\Zdr|string $zdr = 'disabled', RequestOptions|array|null $requestOptions = null, ): WebWebScrapeSitemapResponse; } 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..bb468da 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 tags for tracking usage. Up to 20 tags, each 1 to 50 characters. * @param int $timeoutMs Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes). * @param RequestOpts|null $requestOptions * @@ -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 tags for tracking usage. Up to 20 tags, each 1 to 50 characters. * @param int $timeoutMs Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes). * @param RequestOpts|null $requestOptions * @@ -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..0ab38c5 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 tags for tracking usage. Up to 20 tags, each 1 to 50 characters. * @param int $timeoutMs Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes). * @param 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..365560f 100644 --- a/src/Services/MonitorsRawService.php +++ b/src/Services/MonitorsRawService.php @@ -14,6 +14,9 @@ use ContextDev\Monitors\MonitorCreateParams\Webhook; use ContextDev\Monitors\MonitorDeleteResponse; use ContextDev\Monitors\MonitorGetChangeResponse; +use ContextDev\Monitors\MonitorGetCreditUsageParams; +use ContextDev\Monitors\MonitorGetCreditUsageResponse; +use ContextDev\Monitors\MonitorGetLimitsResponse; use ContextDev\Monitors\MonitorGetResponse; use ContextDev\Monitors\MonitorListAccountChangesParams; use ContextDev\Monitors\MonitorListAccountChangesResponse; @@ -171,11 +174,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 @@ -235,6 +238,62 @@ public function delete( ); } + /** + * @api + * + * Returns credits charged per monitor over an optional [since, until] window, newest spenders first. + * + * @param array{ + * since?: \DateTimeInterface, until?: \DateTimeInterface + * }|MonitorGetCreditUsageParams $params + * @param RequestOpts|null $requestOptions + * + * @return BaseResponse + * + * @throws APIException + */ + public function getCreditUsage( + array|MonitorGetCreditUsageParams $params, + RequestOptions|array|null $requestOptions = null, + ): BaseResponse { + [$parsed, $options] = MonitorGetCreditUsageParams::parseRequest( + $params, + $requestOptions, + ); + + // @phpstan-ignore-next-line return.type + return $this->client->request( + method: 'get', + path: 'monitors/credit-usage', + query: $parsed, + options: $options, + convert: MonitorGetCreditUsageResponse::class, + ); + } + + /** + * @api + * + * Returns how many monitors the account has and the maximum it allows. + * + * @param RequestOpts|null $requestOptions + * + * @return BaseResponse + * + * @throws APIException + */ + public function getLimits( + RequestOptions|array|null $requestOptions = null + ): BaseResponse { + // @phpstan-ignore-next-line return.type + return $this->client->request( + method: 'get', + path: 'monitors/limits', + options: $requestOptions, + convert: MonitorGetLimitsResponse::class, + ); + } + /** * @api * diff --git a/src/Services/MonitorsService.php b/src/Services/MonitorsService.php index d46ad6a..0ed99c1 100644 --- a/src/Services/MonitorsService.php +++ b/src/Services/MonitorsService.php @@ -17,6 +17,8 @@ use ContextDev\Monitors\MonitorCreateParams\Webhook; use ContextDev\Monitors\MonitorDeleteResponse; use ContextDev\Monitors\MonitorGetChangeResponse; +use ContextDev\Monitors\MonitorGetCreditUsageResponse; +use ContextDev\Monitors\MonitorGetLimitsResponse; use ContextDev\Monitors\MonitorGetResponse; use ContextDev\Monitors\MonitorListAccountChangesResponse; use ContextDev\Monitors\MonitorListAccountRunsResponse; @@ -71,7 +73,7 @@ public function __construct(private Client $client) * @param Schedule|ScheduleShape $schedule Run the monitor on a fixed interval defined by a frequency and a unit, e.g. every 6 hours or every 2 days. The total interval (frequency × unit) must be between 10 minutes and 1 year. * @param TargetShape $target discriminated union describing what the monitor watches * @param Mode|value-of $mode Top-level monitor category. Always `web` today; the concrete behavior is described by `target` and `change_detection`. - * @param list $tags user-defined tags for grouping and filtering monitors and their changes + * @param list $tags User-defined tags for grouping and filtering monitors and their changes. Duplicates are removed. * @param Webhook|WebhookShape|null $webhook * @param RequestOpts|null $requestOptions * @@ -132,7 +134,7 @@ public function retrieve( * @param ChangeDetectionShape1 $changeDetection discriminated union describing how changes are detected * @param \ContextDev\Monitors\MonitorUpdateParams\Schedule|ScheduleShape1 $schedule Run the monitor on a fixed interval defined by a frequency and a unit, e.g. every 6 hours or every 2 days. The total interval (frequency × unit) must be between 10 minutes and 1 year. * @param Status|value-of $status - * @param list $tags user-defined tags for grouping and filtering monitors and their changes + * @param list $tags User-defined tags for grouping and filtering monitors and their changes. Duplicates are removed. * @param TargetShape1 $target discriminated union describing what the monitor watches * @param \ContextDev\Monitors\MonitorUpdateParams\Webhook|WebhookShape1|null $webhook set to null to remove the webhook * @param RequestOpts|null $requestOptions @@ -173,14 +175,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 +192,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, @@ -238,14 +242,61 @@ public function delete( return $response->parse(); } + /** + * @api + * + * Returns credits charged per monitor over an optional [since, until] window, newest spenders first. + * + * @param \DateTimeInterface $since only include items at or after this ISO 8601 timestamp + * @param \DateTimeInterface $until only include items before this ISO 8601 timestamp + * @param RequestOpts|null $requestOptions + * + * @throws APIException + */ + public function getCreditUsage( + ?\DateTimeInterface $since = null, + ?\DateTimeInterface $until = null, + RequestOptions|array|null $requestOptions = null, + ): MonitorGetCreditUsageResponse { + $params = Util::removeNulls(['since' => $since, 'until' => $until]); + + // @phpstan-ignore-next-line argument.type + $response = $this->raw->getCreditUsage(params: $params, requestOptions: $requestOptions); + + return $response->parse(); + } + + /** + * @api + * + * Returns how many monitors the account has and the maximum it allows. + * + * @param RequestOpts|null $requestOptions + * + * @throws APIException + */ + public function getLimits( + RequestOptions|array|null $requestOptions = null + ): MonitorGetLimitsResponse { + // @phpstan-ignore-next-line argument.type + $response = $this->raw->getLimits(requestOptions: $requestOptions); + + return $response->parse(); + } + /** * @api * * 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 +304,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 +336,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 +364,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 +376,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 +403,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 +413,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..bd76bd4 100644 --- a/src/Services/ParseRawService.php +++ b/src/Services/ParseRawService.php @@ -11,12 +11,18 @@ use ContextDev\Parse\ParseHandleParams; use ContextDev\Parse\ParseHandleParams\Extension; use ContextDev\Parse\ParseHandleParams\Pdf; +use ContextDev\Parse\ParseHandleParams\Zdr; use ContextDev\Parse\ParseHandleResponse; use ContextDev\RequestOptions; 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 +36,20 @@ 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, + * zdr?: Zdr|value-of, * }|ParseHandleParams $params * @param RequestOpts|null $requestOptions * diff --git a/src/Services/ParseService.php b/src/Services/ParseService.php index fd44ca1..8d6df77 100644 --- a/src/Services/ParseService.php +++ b/src/Services/ParseService.php @@ -9,13 +9,20 @@ 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\ParseHandleParams\Zdr; 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,40 +43,49 @@ 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 Zdr|value-of $zdr Query param: Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true. * @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, + Zdr|string $zdr = 'disabled', 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, + 'zdr' => $zdr, ], ); 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..3ba999f 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 tags for tracking usage. Up to 20 tags, each 1 to 50 characters. * @param int $timeoutMs Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes). * @param RequestOpts|null $requestOptions * @@ -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..3a1a7f4 100644 --- a/src/Services/WebRawService.php +++ b/src/Services/WebRawService.php @@ -23,9 +23,9 @@ 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\WebScreenshotParams\Zdr; use ContextDev\Web\WebScreenshotResponse; use ContextDev\Web\WebSearchParams; use ContextDev\Web\WebSearchParams\Freshness; @@ -45,12 +45,26 @@ /** * @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 ActionShape from \ContextDev\Web\WebWebScrapeHTMLParams\Action + * @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 ActionShape from \ContextDev\Web\WebWebScrapeImagesParams\Action as ActionShape1 + * @phpstan-import-type DedupeShape from \ContextDev\Web\WebWebScrapeImagesParams\Dedupe * @phpstan-import-type EnrichmentShape from \ContextDev\Web\WebWebScrapeImagesParams\Enrichment + * @phpstan-import-type ActionShape from \ContextDev\Web\WebWebScrapeMdParams\Action as ActionShape2 + * @phpstan-import-type IncludeFramesShape from \ContextDev\Web\WebWebScrapeMdParams\IncludeFrames as IncludeFramesShape1 + * @phpstan-import-type 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 @@ -77,7 +91,9 @@ public function __construct(private Client $client) {} * maxDepth?: int, * maxPages?: int, * pdf?: Pdf|PdfShape, + * settleAnimations?: bool, * stopAfterMs?: int, + * tags?: list, * timeoutMs?: int, * waitForMs?: int, * }|WebExtractParams $params @@ -112,7 +128,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 +161,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 +204,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 +247,15 @@ 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, + * zdr?: Zdr|value-of, * }|WebScreenshotParams $params * @param RequestOpts|null $requestOptions * @@ -276,6 +299,7 @@ public function screenshot( * markdownOptions?: MarkdownOptions|MarkdownOptionsShape, * numResults?: int, * queryFanout?: bool, + * tags?: list, * timeoutMs?: int, * }|WebSearchParams $params * @param RequestOpts|null $requestOptions @@ -324,10 +348,12 @@ public function search( * settleAnimations?: bool, * shortenBase64Images?: bool, * stopAfterMs?: int, + * tags?: list, * timeoutMs?: int, * urlRegex?: string, * useMainContentOnly?: bool, * waitForMs?: int, + * zdr?: WebWebCrawlMdParams\Zdr|value-of, * }|WebWebCrawlMdParams $params * @param RequestOpts|null $requestOptions * @@ -357,21 +383,24 @@ public function webCrawlMd( /** * @api * - * Scrapes the given URL and returns the raw HTML content of the page. + * Scrapes the given URL and returns the raw HTML content of the page. The base request costs 1 credit; requests with browser actions cost 2 credits. * * @param array{ * url: string, + * actions?: list|null, * 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, + * zdr?: WebWebScrapeHTMLParams\Zdr|value-of, * }|WebWebScrapeHTMLParams $params * @param RequestOpts|null $requestOptions * @@ -401,16 +430,18 @@ public function webScrapeHTML( /** * @api * - * 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. + * 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, or 2 credits with browser actions. When enrichment is enabled, the entire call costs 5 credits, including requests that also use actions. * * @param array{ * url: string, - * dedupe?: bool, - * enrichment?: Enrichment|EnrichmentShape, + * actions?: list|null, + * 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 * @@ -446,7 +477,7 @@ public function webScrapeImages( * * | HTTP status | Billed? | Meaning | * | --- | --- | --- | - * | 200 | Yes — 1 credit | Successful scrape, including a zero-length result when includeSelectors matched nothing | + * | 200 | Yes — 1 credit, or 2 credits with actions | Successful scrape, including a zero-length result when includeSelectors matched nothing | * | 400 | No | Invalid input, skipped PDF, or the page could not be scraped | * | 401 / 403 | No | Invalid/disabled key, insufficient permissions, or credits exhausted; inspect error_code | * | 404 | No | Target page returned or fingerprinted as not found | @@ -457,20 +488,23 @@ public function webScrapeImages( * * @param array{ * url: string, + * actions?: list|null, * 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, + * zdr?: WebWebScrapeMdParams\Zdr|value-of, * }|WebWebScrapeMdParams $params * @param RequestOpts|null $requestOptions * @@ -506,8 +540,11 @@ public function webScrapeMd( * domain: string, * headers?: array, * maxLinks?: int, + * sitemapURL?: string, + * tags?: list, * timeoutMs?: int, * urlRegex?: string, + * zdr?: WebWebScrapeSitemapParams\Zdr|value-of, * }|WebWebScrapeSitemapParams $params * @param RequestOpts|null $requestOptions * @@ -528,7 +565,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..a4a1799 100644 --- a/src/Services/WebService.php +++ b/src/Services/WebService.php @@ -17,9 +17,10 @@ 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\WebScreenshotParams\Zdr; use ContextDev\Web\WebScreenshotResponse; use ContextDev\Web\WebSearchParams\Freshness; use ContextDev\Web\WebSearchParams\MarkdownOptions; @@ -33,12 +34,26 @@ /** * @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 ActionShape from \ContextDev\Web\WebWebScrapeHTMLParams\Action + * @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 ActionShape from \ContextDev\Web\WebWebScrapeImagesParams\Action as ActionShape1 + * @phpstan-import-type DedupeShape from \ContextDev\Web\WebWebScrapeImagesParams\Dedupe * @phpstan-import-type EnrichmentShape from \ContextDev\Web\WebWebScrapeImagesParams\Enrichment + * @phpstan-import-type ActionShape from \ContextDev\Web\WebWebScrapeMdParams\Action as ActionShape2 + * @phpstan-import-type IncludeFramesShape from \ContextDev\Web\WebWebScrapeMdParams\IncludeFrames as IncludeFramesShape1 + * @phpstan-import-type 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 @@ -71,7 +86,9 @@ public function __construct(private Client $client) * @param int $maxDepth Optional maximum link depth from the starting URL (0 = only the starting page). If omitted, there is no crawl depth limit. * @param int $maxPages Maximum number of pages to analyze for extraction. Hard cap: 50. Defaults to 5. * @param Pdf|PdfShape $pdf + * @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 int $stopAfterMs Soft time budget for the crawl in milliseconds. Min: 10000 (10s). Max: 110000 (110s). Default: 80000 (80s). + * @param list $tags Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. * @param int $timeoutMs Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes). * @param int $waitForMs optional browser wait time in milliseconds after initial page load for each crawled page * @param RequestOpts|null $requestOptions @@ -89,7 +106,9 @@ public function extract( ?int $maxDepth = null, int $maxPages = 5, Pdf|array $pdf = ['shouldParse' => true], + bool $settleAnimations = false, int $stopAfterMs = 80000, + ?array $tags = null, ?int $timeoutMs = null, ?int $waitForMs = null, RequestOptions|array|null $requestOptions = null, @@ -106,7 +125,9 @@ public function extract( 'maxDepth' => $maxDepth, 'maxPages' => $maxPages, 'pdf' => $pdf, + 'settleAnimations' => $settleAnimations, 'stopAfterMs' => $stopAfterMs, + 'tags' => $tags, 'timeoutMs' => $timeoutMs, 'waitForMs' => $waitForMs, ], @@ -125,6 +146,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 +155,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 +163,7 @@ public function extractCompetitors( [ 'domain' => $domain, 'numCompetitors' => $numCompetitors, + 'tags' => $tags, 'timeoutMs' => $timeoutMs, ], ); @@ -157,7 +181,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 +191,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 +201,7 @@ public function extractFonts( 'directURL' => $directURL, 'domain' => $domain, 'maxAgeMs' => $maxAgeMs, + 'tags' => $tags, 'timeoutMs' => $timeoutMs, ], ); @@ -193,7 +220,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 +231,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 +242,7 @@ public function extractStyleguide( 'directURL' => $directURL, 'domain' => $domain, 'maxAgeMs' => $maxAgeMs, + 'tags' => $tags, 'timeoutMs' => $timeoutMs, ], ); @@ -229,17 +259,19 @@ 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 Zdr|value-of $zdr Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true. * @param RequestOpts|null $requestOptions * * @throws APIException @@ -250,13 +282,15 @@ 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, + Zdr|string $zdr = 'disabled', RequestOptions|array|null $requestOptions = null, ): WebScreenshotResponse { $params = Util::removeNulls( @@ -270,9 +304,11 @@ public function screenshot( 'maxAgeMs' => $maxAgeMs, 'page' => $page, 'scrollOffset' => $scrollOffset, + 'tags' => $tags, 'timeoutMs' => $timeoutMs, 'viewport' => $viewport, 'waitForMs' => $waitForMs, + 'zdr' => $zdr, ], ); @@ -295,6 +331,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 tags for tracking usage. Up to 20 tags, each 1 to 50 characters. * @param int $timeoutMs Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes). * @param RequestOpts|null $requestOptions * @@ -309,6 +346,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 +360,7 @@ public function search( 'markdownOptions' => $markdownOptions, 'numResults' => $numResults, 'queryFanout' => $queryFanout, + 'tags' => $tags, 'timeoutMs' => $timeoutMs, ], ); @@ -352,10 +391,12 @@ 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 tags for tracking usage. Up to 20 tags, each 1 to 50 characters. * @param int $timeoutMs Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes). * @param 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 * @param int $waitForMs Optional browser wait time in milliseconds after initial page load for each crawled page. Min: 0. Max: 30000 (30 seconds). + * @param \ContextDev\Web\WebWebCrawlMdParams\Zdr|value-of<\ContextDev\Web\WebWebCrawlMdParams\Zdr> $zdr Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true. * @param RequestOpts|null $requestOptions * * @throws APIException @@ -378,10 +419,12 @@ public function webCrawlMd( bool $settleAnimations = false, bool $shortenBase64Images = true, int $stopAfterMs = 80000, + ?array $tags = null, ?int $timeoutMs = null, ?string $urlRegex = null, bool $useMainContentOnly = false, ?int $waitForMs = null, + \ContextDev\Web\WebWebCrawlMdParams\Zdr|string $zdr = 'disabled', RequestOptions|array|null $requestOptions = null, ): WebWebCrawlMdResponse { $params = Util::removeNulls( @@ -401,10 +444,12 @@ public function webCrawlMd( 'settleAnimations' => $settleAnimations, 'shortenBase64Images' => $shortenBase64Images, 'stopAfterMs' => $stopAfterMs, + 'tags' => $tags, 'timeoutMs' => $timeoutMs, 'urlRegex' => $urlRegex, 'useMainContentOnly' => $useMainContentOnly, 'waitForMs' => $waitForMs, + 'zdr' => $zdr, ], ); @@ -417,44 +462,51 @@ public function webCrawlMd( /** * @api * - * Scrapes the given URL and returns the raw HTML content of the page. + * Scrapes the given URL and returns the raw HTML content of the page. The base request costs 1 credit; requests with browser actions cost 2 credits. * * @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 list|null $actions Optional browser actions executed in array order after the page loads and before content is captured. Requires a paid plan. Send a JSON array in the query parameter. Maximum: 5 actions. + * @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 \ContextDev\Web\WebWebScrapeHTMLParams\Zdr|value-of<\ContextDev\Web\WebWebScrapeHTMLParams\Zdr> $zdr Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true. * @param RequestOpts|null $requestOptions * * @throws APIException */ public function webScrapeHTML( string $url, + ?array $actions = null, \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, + \ContextDev\Web\WebWebScrapeHTMLParams\Zdr|string $zdr = 'disabled', RequestOptions|array|null $requestOptions = null, ): WebWebScrapeHTMLResponse { $params = Util::removeNulls( [ 'url' => $url, + 'actions' => $actions, 'country' => $country, 'excludeSelectors' => $excludeSelectors, 'headers' => $headers, @@ -463,9 +515,11 @@ public function webScrapeHTML( 'maxAgeMs' => $maxAgeMs, 'pdf' => $pdf, 'settleAnimations' => $settleAnimations, + 'tags' => $tags, 'timeoutMs' => $timeoutMs, 'useMainContentOnly' => $useMainContentOnly, 'waitForMs' => $waitForMs, + 'zdr' => $zdr, ], ); @@ -478,25 +532,29 @@ public function webScrapeHTML( /** * @api * - * 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. + * 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, or 2 credits with browser actions. When enrichment is enabled, the entire call costs 5 credits, including requests that also use actions. * * @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 list|null $actions Optional browser actions executed in array order after the page loads and before content is captured. Requires a paid plan. Send a JSON array in the query parameter. Maximum: 5 actions. + * @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, + ?array $actions = null, + 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, @@ -504,10 +562,12 @@ public function webScrapeImages( $params = Util::removeNulls( [ 'url' => $url, + 'actions' => $actions, 'dedupe' => $dedupe, 'enrichment' => $enrichment, 'headers' => $headers, 'maxAgeMs' => $maxAgeMs, + 'tags' => $tags, 'timeoutMs' => $timeoutMs, 'waitForMs' => $waitForMs, ], @@ -528,7 +588,7 @@ public function webScrapeImages( * * | HTTP status | Billed? | Meaning | * | --- | --- | --- | - * | 200 | Yes — 1 credit | Successful scrape, including a zero-length result when includeSelectors matched nothing | + * | 200 | Yes — 1 credit, or 2 credits with actions | Successful scrape, including a zero-length result when includeSelectors matched nothing | * | 400 | No | Invalid input, skipped PDF, or the page could not be scraped | * | 401 / 403 | No | Invalid/disabled key, insufficient permissions, or credits exhausted; inspect error_code | * | 404 | No | Target page returned or fingerprinted as not found | @@ -538,47 +598,54 @@ 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 list|null $actions Optional browser actions executed in array order after the page loads and before content is captured. Requires a paid plan. Send a JSON array in the query parameter. Maximum: 5 actions. + * @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 \ContextDev\Web\WebWebScrapeMdParams\Zdr|value-of<\ContextDev\Web\WebWebScrapeMdParams\Zdr> $zdr Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true. * @param RequestOpts|null $requestOptions * * @throws APIException */ public function webScrapeMd( string $url, + ?array $actions = null, \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, + \ContextDev\Web\WebWebScrapeMdParams\Zdr|string $zdr = 'disabled', RequestOptions|array|null $requestOptions = null, ): WebWebScrapeMdResponse { $params = Util::removeNulls( [ 'url' => $url, + 'actions' => $actions, 'country' => $country, 'excludeSelectors' => $excludeSelectors, 'headers' => $headers, @@ -590,9 +657,11 @@ public function webScrapeMd( 'pdf' => $pdf, 'settleAnimations' => $settleAnimations, 'shortenBase64Images' => $shortenBase64Images, + 'tags' => $tags, 'timeoutMs' => $timeoutMs, 'useMainContentOnly' => $useMainContentOnly, 'waitForMs' => $waitForMs, + 'zdr' => $zdr, ], ); @@ -610,8 +679,11 @@ 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 \ContextDev\Web\WebWebScrapeSitemapParams\Zdr|value-of<\ContextDev\Web\WebWebScrapeSitemapParams\Zdr> $zdr Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true. * @param RequestOpts|null $requestOptions * * @throws APIException @@ -620,8 +692,11 @@ public function webScrapeSitemap( string $domain, ?array $headers = null, int $maxLinks = 10000, + ?string $sitemapURL = null, + ?array $tags = null, ?int $timeoutMs = null, ?string $urlRegex = null, + \ContextDev\Web\WebWebScrapeSitemapParams\Zdr|string $zdr = 'disabled', RequestOptions|array|null $requestOptions = null, ): WebWebScrapeSitemapResponse { $params = Util::removeNulls( @@ -629,8 +704,11 @@ public function webScrapeSitemap( 'domain' => $domain, 'headers' => $headers, 'maxLinks' => $maxLinks, + 'sitemapURL' => $sitemapURL, + 'tags' => $tags, 'timeoutMs' => $timeoutMs, 'urlRegex' => $urlRegex, + 'zdr' => $zdr, ], ); diff --git a/src/Utility/UtilityPrefetchParams.php b/src/Utility/UtilityPrefetchParams.php index 0082269..2025df6 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 tags for tracking usage. Up to 20 tags, each 1 to 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 tags for tracking usage. Up to 20 tags, each 1 to 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..1140f0f 100644 --- a/src/Web/WebExtractParams.php +++ b/src/Web/WebExtractParams.php @@ -29,7 +29,9 @@ * maxDepth?: int|null, * maxPages?: int|null, * pdf?: null|Pdf|PdfShape, + * settleAnimations?: bool|null, * stopAfterMs?: int|null, + * tags?: list|null, * timeoutMs?: int|null, * waitForMs?: int|null, * } @@ -99,12 +101,26 @@ final class WebExtractParams implements BaseModel #[Optional] public ?Pdf $pdf; + /** + * 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. + */ + #[Optional] + public ?bool $settleAnimations; + /** * Soft time budget for the crawl in milliseconds. Min: 10000 (10s). Max: 110000 (110s). Default: 80000 (80s). */ #[Optional] public ?int $stopAfterMs; + /** + * Optional tags for tracking usage. Up to 20 tags, each 1 to 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 +159,7 @@ public function __construct() * * @param array $schema * @param Pdf|PdfShape|null $pdf + * @param list|null $tags */ public static function with( array $schema, @@ -155,7 +172,9 @@ public static function with( ?int $maxDepth = null, ?int $maxPages = null, Pdf|array|null $pdf = null, + ?bool $settleAnimations = null, ?int $stopAfterMs = null, + ?array $tags = null, ?int $timeoutMs = null, ?int $waitForMs = null, ): self { @@ -172,7 +191,9 @@ public static function with( null !== $maxDepth && $self['maxDepth'] = $maxDepth; null !== $maxPages && $self['maxPages'] = $maxPages; null !== $pdf && $self['pdf'] = $pdf; + null !== $settleAnimations && $self['settleAnimations'] = $settleAnimations; null !== $stopAfterMs && $self['stopAfterMs'] = $stopAfterMs; + null !== $tags && $self['tags'] = $tags; null !== $timeoutMs && $self['timeoutMs'] = $timeoutMs; null !== $waitForMs && $self['waitForMs'] = $waitForMs; @@ -291,6 +312,17 @@ public function withPdf(Pdf|array $pdf): self return $self; } + /** + * 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. + */ + public function withSettleAnimations(bool $settleAnimations): self + { + $self = clone $this; + $self['settleAnimations'] = $settleAnimations; + + return $self; + } + /** * Soft time budget for the crawl in milliseconds. Min: 10000 (10s). Max: 110000 (110s). Default: 80000 (80s). */ @@ -302,6 +334,19 @@ public function withStopAfterMs(int $stopAfterMs): self return $self; } + /** + * Optional tags for tracking usage. Up to 20 tags, each 1 to 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..bf56e01 100644 --- a/src/Web/WebScreenshotParams.php +++ b/src/Web/WebScreenshotParams.php @@ -12,14 +12,18 @@ 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\WebScreenshotParams\Zdr; /** * Capture a screenshot of a website. * * @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,13 +32,15 @@ * 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, + * zdr?: null|Zdr|value-of, * } */ final class WebScreenshotParams implements BaseModel @@ -52,7 +58,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 +88,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 +110,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,11 +134,19 @@ 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; + /** + * Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true. + * + * @var value-of|null $zdr + */ + #[Optional(enum: Zdr::class)] + public ?string $zdr; + public function __construct() { $this->initialize(); @@ -138,9 +160,11 @@ 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 + * @param Zdr|value-of|null $zdr */ public static function with( ColorScheme|string|null $colorScheme = null, @@ -148,13 +172,15 @@ 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, + Zdr|string|null $zdr = null, ): self { $self = new self; @@ -167,9 +193,11 @@ 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; + null !== $zdr && $self['zdr'] = $zdr; return $self; } @@ -188,7 +216,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 +267,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 +281,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 +305,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 +313,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,13 +351,26 @@ 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; return $self; } + + /** + * Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true. + * + * @param Zdr|value-of $zdr + */ + public function withZdr(Zdr|string $zdr): self + { + $self = clone $this; + $self['zdr'] = $zdr; + + return $self; + } } 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 tags for tracking usage. Up to 20 tags, each 1 to 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 tags for tracking usage. Up to 20 tags, each 1 to 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..89a59a0 100644 --- a/src/Web/WebWebCrawlMdParams.php +++ b/src/Web/WebWebCrawlMdParams.php @@ -11,6 +11,7 @@ use ContextDev\Core\Contracts\BaseModel; use ContextDev\Web\WebWebCrawlMdParams\Country; use ContextDev\Web\WebWebCrawlMdParams\Pdf; +use ContextDev\Web\WebWebCrawlMdParams\Zdr; /** * Performs a crawl starting from a given URL, extracts page content as Markdown, and returns results for all crawled pages. @@ -35,10 +36,12 @@ * settleAnimations?: bool|null, * shortenBase64Images?: bool|null, * stopAfterMs?: int|null, + * tags?: list|null, * timeoutMs?: int|null, * urlRegex?: string|null, * useMainContentOnly?: bool|null, * waitForMs?: int|null, + * zdr?: null|Zdr|value-of, * } */ final class WebWebCrawlMdParams implements BaseModel @@ -143,6 +146,14 @@ final class WebWebCrawlMdParams implements BaseModel #[Optional] public ?int $stopAfterMs; + /** + * Optional tags for tracking usage. Up to 20 tags, each 1 to 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). */ @@ -167,6 +178,14 @@ final class WebWebCrawlMdParams implements BaseModel #[Optional] public ?int $waitForMs; + /** + * Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true. + * + * @var value-of|null $zdr + */ + #[Optional(enum: Zdr::class)] + public ?string $zdr; + /** * `new WebWebCrawlMdParams()` is missing required properties by the API. * @@ -195,6 +214,8 @@ public function __construct() * @param list|null $excludeSelectors * @param list|null $includeSelectors * @param Pdf|PdfShape|null $pdf + * @param list|null $tags + * @param Zdr|value-of|null $zdr */ public static function with( string $url, @@ -212,10 +233,12 @@ 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, ?int $waitForMs = null, + Zdr|string|null $zdr = null, ): self { $self = new self; @@ -235,10 +258,12 @@ 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; null !== $waitForMs && $self['waitForMs'] = $waitForMs; + null !== $zdr && $self['zdr'] = $zdr; return $self; } @@ -416,6 +441,19 @@ public function withStopAfterMs(int $stopAfterMs): self return $self; } + /** + * Optional tags for tracking usage. Up to 20 tags, each 1 to 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). */ @@ -459,4 +497,17 @@ public function withWaitForMs(int $waitForMs): self return $self; } + + /** + * Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true. + * + * @param Zdr|value-of $zdr + */ + public function withZdr(Zdr|string $zdr): self + { + $self = clone $this; + $self['zdr'] = $zdr; + + return $self; + } } diff --git a/src/Web/WebWebCrawlMdParams/Zdr.php b/src/Web/WebWebCrawlMdParams/Zdr.php new file mode 100644 index 0000000..1fbf6b0 --- /dev/null +++ b/src/Web/WebWebCrawlMdParams/Zdr.php @@ -0,0 +1,15 @@ +|null, * 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, + * zdr?: null|Zdr|value-of, * } */ final class WebWebScrapeHTMLParams implements BaseModel @@ -47,7 +64,15 @@ 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. + * Optional browser actions executed in array order after the page loads and before content is captured. Requires a paid plan. Send a JSON array in the query parameter. Maximum: 5 actions. + * + * @var list|null $actions + */ + #[Optional(list: Action::class, nullable: true)] + public ?array $actions; + + /** + * 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 +84,7 @@ final class WebWebScrapeHTMLParams implements BaseModel * * @var list|null $excludeSelectors */ - #[Optional(list: 'string')] + #[Optional(list: 'string', nullable: true)] public ?array $excludeSelectors; /** @@ -72,22 +97,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 +125,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,16 +147,26 @@ 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; + /** + * Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true. + * + * @var value-of|null $zdr + */ + #[Optional(enum: Zdr::class)] + public ?string $zdr; + /** * `new WebWebScrapeHTMLParams()` is missing required properties by the API. * @@ -144,30 +191,40 @@ public function __construct() * * You must use named parameters to construct any parameters with a default value. * + * @param list|null $actions * @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 + * @param Zdr|value-of|null $zdr */ public static function with( string $url, + ?array $actions = null, 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, + Zdr|string|null $zdr = null, ): self { $self = new self; $self['url'] = $url; + null !== $actions && $self['actions'] = $actions; null !== $country && $self['country'] = $country; null !== $excludeSelectors && $self['excludeSelectors'] = $excludeSelectors; null !== $headers && $self['headers'] = $headers; @@ -176,9 +233,11 @@ 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; + null !== $zdr && $self['zdr'] = $zdr; return $self; } @@ -195,7 +254,20 @@ 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. + * Optional browser actions executed in array order after the page loads and before content is captured. Requires a paid plan. Send a JSON array in the query parameter. Maximum: 5 actions. + * + * @param list|null $actions + */ + public function withActions(?array $actions): self + { + $self = clone $this; + $self['actions'] = $actions; + + return $self; + } + + /** + * 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 +282,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 +307,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 +322,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 +335,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 +358,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 +396,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,11 +411,24 @@ 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; return $self; } + + /** + * Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true. + * + * @param Zdr|value-of $zdr + */ + public function withZdr(Zdr|string $zdr): self + { + $self = clone $this; + $self['zdr'] = $zdr; + + return $self; + } } diff --git a/src/Web/WebWebScrapeHTMLParams/Action.php b/src/Web/WebWebScrapeHTMLParams/Action.php new file mode 100644 index 0000000..02d0da1 --- /dev/null +++ b/src/Web/WebWebScrapeHTMLParams/Action.php @@ -0,0 +1,41 @@ +|array + */ + public static function variants(): array + { + return [ + 'wait' => WebScrapeWaitAction::class, + 'perform' => WebScrapePerformAction::class, + ]; + } +} diff --git a/src/Web/WebWebScrapeHTMLParams/Action/WebScrapePerformAction.php b/src/Web/WebWebScrapeHTMLParams/Action/WebScrapePerformAction.php new file mode 100644 index 0000000..b546008 --- /dev/null +++ b/src/Web/WebWebScrapeHTMLParams/Action/WebScrapePerformAction.php @@ -0,0 +1,79 @@ + */ + use SdkModel; + + /** @var 'perform' $do */ + #[Required] + public string $do = 'perform'; + + #[Required] + public string $action; + + /** + * `new WebScrapePerformAction()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * WebScrapePerformAction::with(action: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new WebScrapePerformAction)->withAction(...) + * ``` + */ + 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 $action): self + { + $self = new self; + + $self['action'] = $action; + + return $self; + } + + public function withAction(string $action): self + { + $self = clone $this; + $self['action'] = $action; + + return $self; + } + + /** + * @param 'perform' $do + */ + public function withDo(string $do): self + { + $self = clone $this; + $self['do'] = $do; + + return $self; + } +} diff --git a/src/Web/WebWebScrapeHTMLParams/Action/WebScrapeWaitAction.php b/src/Web/WebWebScrapeHTMLParams/Action/WebScrapeWaitAction.php new file mode 100644 index 0000000..1992238 --- /dev/null +++ b/src/Web/WebWebScrapeHTMLParams/Action/WebScrapeWaitAction.php @@ -0,0 +1,79 @@ + */ + use SdkModel; + + /** @var 'wait' $do */ + #[Required] + public string $do = 'wait'; + + #[Required] + public int $timeMs; + + /** + * `new WebScrapeWaitAction()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * WebScrapeWaitAction::with(timeMs: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new WebScrapeWaitAction)->withTimeMs(...) + * ``` + */ + public function __construct() + { + $this->initialize(); + } + + /** + * Construct an instance from the required parameters. + * + * You must use named parameters to construct any parameters with a default value. + */ + public static function with(int $timeMs): self + { + $self = new self; + + $self['timeMs'] = $timeMs; + + return $self; + } + + /** + * @param 'wait' $do + */ + public function withDo(string $do): self + { + $self = clone $this; + $self['do'] = $do; + + return $self; + } + + public function withTimeMs(int $timeMs): self + { + $self = clone $this; + $self['timeMs'] = $timeMs; + + return $self; + } +} 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, + * dedupe?: DedupeShape|null, * enrichment?: null|Enrichment|EnrichmentShape, * headers?: array|null, * maxAgeMs?: int|null, + * tags?: list|null, * timeoutMs?: int|null, * waitForMs?: int|null, * } @@ -40,16 +49,26 @@ final class WebWebScrapeImagesParams implements BaseModel #[Required] public string $url; + /** + * Optional browser actions executed in array order after the page loads and before content is captured. Requires a paid plan. Send a JSON array in the query parameter. Maximum: 5 actions. + * + * @var list|null $actions + */ + #[Optional(list: Action::class, nullable: true)] + public ?array $actions; + /** * 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 +82,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 +102,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 +129,20 @@ public function __construct() * * You must use named parameters to construct any parameters with a default value. * + * @param list|null $actions + * @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, + ?array $actions = 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 { @@ -118,10 +150,12 @@ public static function with( $self['url'] = $url; + null !== $actions && $self['actions'] = $actions; null !== $dedupe && $self['dedupe'] = $dedupe; 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; @@ -139,10 +173,25 @@ public function withURL(string $url): self return $self; } + /** + * Optional browser actions executed in array order after the page loads and before content is captured. Requires a paid plan. Send a JSON array in the query parameter. Maximum: 5 actions. + * + * @param list|null $actions + */ + public function withActions(?array $actions): self + { + $self = clone $this; + $self['actions'] = $actions; + + return $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 +202,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 +228,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 +236,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 +263,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/Action.php b/src/Web/WebWebScrapeImagesParams/Action.php new file mode 100644 index 0000000..9f64d83 --- /dev/null +++ b/src/Web/WebWebScrapeImagesParams/Action.php @@ -0,0 +1,41 @@ +|array + */ + public static function variants(): array + { + return [ + 'wait' => WebScrapeWaitAction::class, + 'perform' => WebScrapePerformAction::class, + ]; + } +} diff --git a/src/Web/WebWebScrapeImagesParams/Action/WebScrapePerformAction.php b/src/Web/WebWebScrapeImagesParams/Action/WebScrapePerformAction.php new file mode 100644 index 0000000..1f9f147 --- /dev/null +++ b/src/Web/WebWebScrapeImagesParams/Action/WebScrapePerformAction.php @@ -0,0 +1,79 @@ + */ + use SdkModel; + + /** @var 'perform' $do */ + #[Required] + public string $do = 'perform'; + + #[Required] + public string $action; + + /** + * `new WebScrapePerformAction()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * WebScrapePerformAction::with(action: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new WebScrapePerformAction)->withAction(...) + * ``` + */ + 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 $action): self + { + $self = new self; + + $self['action'] = $action; + + return $self; + } + + public function withAction(string $action): self + { + $self = clone $this; + $self['action'] = $action; + + return $self; + } + + /** + * @param 'perform' $do + */ + public function withDo(string $do): self + { + $self = clone $this; + $self['do'] = $do; + + return $self; + } +} diff --git a/src/Web/WebWebScrapeImagesParams/Action/WebScrapeWaitAction.php b/src/Web/WebWebScrapeImagesParams/Action/WebScrapeWaitAction.php new file mode 100644 index 0000000..c47f340 --- /dev/null +++ b/src/Web/WebWebScrapeImagesParams/Action/WebScrapeWaitAction.php @@ -0,0 +1,79 @@ + */ + use SdkModel; + + /** @var 'wait' $do */ + #[Required] + public string $do = 'wait'; + + #[Required] + public int $timeMs; + + /** + * `new WebScrapeWaitAction()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * WebScrapeWaitAction::with(timeMs: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new WebScrapeWaitAction)->withTimeMs(...) + * ``` + */ + public function __construct() + { + $this->initialize(); + } + + /** + * Construct an instance from the required parameters. + * + * You must use named parameters to construct any parameters with a default value. + */ + public static function with(int $timeMs): self + { + $self = new self; + + $self['timeMs'] = $timeMs; + + return $self; + } + + /** + * @param 'wait' $do + */ + public function withDo(string $do): self + { + $self = clone $this; + $self['do'] = $do; + + return $self; + } + + public function withTimeMs(int $timeMs): self + { + $self = clone $this; + $self['timeMs'] = $timeMs; + + return $self; + } +} 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 @@ +|null, * country?: null|Country|value-of, * 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, + * zdr?: null|Zdr|value-of, * } */ final class WebWebScrapeMdParams implements BaseModel @@ -63,7 +89,15 @@ 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. + * Optional browser actions executed in array order after the page loads and before content is captured. Requires a paid plan. Send a JSON array in the query parameter. Maximum: 5 actions. + * + * @var list|null $actions + */ + #[Optional(list: Action::class, nullable: true)] + public ?array $actions; + + /** + * 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 +109,7 @@ final class WebWebScrapeMdParams implements BaseModel * * @var list|null $excludeSelectors */ - #[Optional(list: 'string')] + #[Optional(list: 'string', nullable: true)] public ?array $excludeSelectors; /** @@ -88,34 +122,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 +166,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,16 +196,26 @@ 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; + /** + * Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true. + * + * @var value-of|null $zdr + */ + #[Optional(enum: Zdr::class)] + public ?string $zdr; + /** * `new WebWebScrapeMdParams()` is missing required properties by the API. * @@ -178,33 +240,46 @@ public function __construct() * * You must use named parameters to construct any parameters with a default value. * + * @param list|null $actions * @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 + * @param Zdr|value-of|null $zdr */ public static function with( string $url, + ?array $actions = null, 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, + Zdr|string|null $zdr = null, ): self { $self = new self; $self['url'] = $url; + null !== $actions && $self['actions'] = $actions; null !== $country && $self['country'] = $country; null !== $excludeSelectors && $self['excludeSelectors'] = $excludeSelectors; null !== $headers && $self['headers'] = $headers; @@ -216,9 +291,11 @@ 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; + null !== $zdr && $self['zdr'] = $zdr; return $self; } @@ -235,7 +312,20 @@ 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. + * Optional browser actions executed in array order after the page loads and before content is captured. Requires a paid plan. Send a JSON array in the query parameter. Maximum: 5 actions. + * + * @param list|null $actions + */ + public function withActions(?array $actions): self + { + $self = clone $this; + $self['actions'] = $actions; + + return $self; + } + + /** + * 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 +340,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 +365,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 +379,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 +393,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 +408,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 +421,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 +444,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 +458,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 +496,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,11 +511,24 @@ 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; return $self; } + + /** + * Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true. + * + * @param Zdr|value-of $zdr + */ + public function withZdr(Zdr|string $zdr): self + { + $self = clone $this; + $self['zdr'] = $zdr; + + return $self; + } } diff --git a/src/Web/WebWebScrapeMdParams/Action.php b/src/Web/WebWebScrapeMdParams/Action.php new file mode 100644 index 0000000..349deb0 --- /dev/null +++ b/src/Web/WebWebScrapeMdParams/Action.php @@ -0,0 +1,41 @@ +|array + */ + public static function variants(): array + { + return [ + 'wait' => WebScrapeWaitAction::class, + 'perform' => WebScrapePerformAction::class, + ]; + } +} diff --git a/src/Web/WebWebScrapeMdParams/Action/WebScrapePerformAction.php b/src/Web/WebWebScrapeMdParams/Action/WebScrapePerformAction.php new file mode 100644 index 0000000..7910b74 --- /dev/null +++ b/src/Web/WebWebScrapeMdParams/Action/WebScrapePerformAction.php @@ -0,0 +1,79 @@ + */ + use SdkModel; + + /** @var 'perform' $do */ + #[Required] + public string $do = 'perform'; + + #[Required] + public string $action; + + /** + * `new WebScrapePerformAction()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * WebScrapePerformAction::with(action: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new WebScrapePerformAction)->withAction(...) + * ``` + */ + 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 $action): self + { + $self = new self; + + $self['action'] = $action; + + return $self; + } + + public function withAction(string $action): self + { + $self = clone $this; + $self['action'] = $action; + + return $self; + } + + /** + * @param 'perform' $do + */ + public function withDo(string $do): self + { + $self = clone $this; + $self['do'] = $do; + + return $self; + } +} diff --git a/src/Web/WebWebScrapeMdParams/Action/WebScrapeWaitAction.php b/src/Web/WebWebScrapeMdParams/Action/WebScrapeWaitAction.php new file mode 100644 index 0000000..c5943ee --- /dev/null +++ b/src/Web/WebWebScrapeMdParams/Action/WebScrapeWaitAction.php @@ -0,0 +1,79 @@ + */ + use SdkModel; + + /** @var 'wait' $do */ + #[Required] + public string $do = 'wait'; + + #[Required] + public int $timeMs; + + /** + * `new WebScrapeWaitAction()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * WebScrapeWaitAction::with(timeMs: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new WebScrapeWaitAction)->withTimeMs(...) + * ``` + */ + public function __construct() + { + $this->initialize(); + } + + /** + * Construct an instance from the required parameters. + * + * You must use named parameters to construct any parameters with a default value. + */ + public static function with(int $timeMs): self + { + $self = new self; + + $self['timeMs'] = $timeMs; + + return $self; + } + + /** + * @param 'wait' $do + */ + public function withDo(string $do): self + { + $self = clone $this; + $self['do'] = $do; + + return $self; + } + + public function withTimeMs(int $timeMs): self + { + $self = clone $this; + $self['timeMs'] = $timeMs; + + return $self; + } +} 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, + * zdr?: null|Zdr|value-of, * } */ final class WebWebScrapeSitemapParams implements BaseModel @@ -49,6 +53,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). */ @@ -61,6 +79,14 @@ final class WebWebScrapeSitemapParams implements BaseModel #[Optional] public ?string $urlRegex; + /** + * Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true. + * + * @var value-of|null $zdr + */ + #[Optional(enum: Zdr::class)] + public ?string $zdr; + /** * `new WebWebScrapeSitemapParams()` is missing required properties by the API. * @@ -86,13 +112,18 @@ public function __construct() * You must use named parameters to construct any parameters with a default value. * * @param array|null $headers + * @param list|null $tags + * @param Zdr|value-of|null $zdr */ public static function with( string $domain, ?array $headers = null, ?int $maxLinks = null, + ?string $sitemapURL = null, + ?array $tags = null, ?int $timeoutMs = null, ?string $urlRegex = null, + Zdr|string|null $zdr = null, ): self { $self = new self; @@ -100,8 +131,11 @@ 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; + null !== $zdr && $self['zdr'] = $zdr; return $self; } @@ -141,6 +175,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). */ @@ -162,4 +220,17 @@ public function withURLRegex(string $urlRegex): self return $self; } + + /** + * Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true. + * + * @param Zdr|value-of $zdr + */ + public function withZdr(Zdr|string $zdr): self + { + $self = clone $this; + $self['zdr'] = $zdr; + + return $self; + } } diff --git a/src/Web/WebWebScrapeSitemapParams/Zdr.php b/src/Web/WebWebScrapeSitemapParams/Zdr.php new file mode 100644 index 0000000..c82b03b --- /dev/null +++ b/src/Web/WebWebScrapeSitemapParams/Zdr.php @@ -0,0 +1,15 @@ +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/MonitorsTest.php b/tests/Services/MonitorsTest.php index 904d9d4..d60e90d 100644 --- a/tests/Services/MonitorsTest.php +++ b/tests/Services/MonitorsTest.php @@ -6,6 +6,8 @@ use ContextDev\Core\Util; use ContextDev\Monitors\MonitorDeleteResponse; use ContextDev\Monitors\MonitorGetChangeResponse; +use ContextDev\Monitors\MonitorGetCreditUsageResponse; +use ContextDev\Monitors\MonitorGetLimitsResponse; use ContextDev\Monitors\MonitorGetResponse; use ContextDev\Monitors\MonitorListAccountChangesResponse; use ContextDev\Monitors\MonitorListAccountRunsResponse; @@ -136,6 +138,32 @@ public function testDelete(): void $this->assertInstanceOf(MonitorDeleteResponse::class, $result); } + #[Test] + public function testGetCreditUsage(): void + { + if (UnsupportedMockTests::$skip) { + $this->markTestSkipped('Mock server tests are disabled'); + } + + $result = $this->client->monitors->getCreditUsage(); + + // @phpstan-ignore-next-line method.alreadyNarrowedType + $this->assertInstanceOf(MonitorGetCreditUsageResponse::class, $result); + } + + #[Test] + public function testGetLimits(): void + { + if (UnsupportedMockTests::$skip) { + $this->markTestSkipped('Mock server tests are disabled'); + } + + $result = $this->client->monitors->getLimits(); + + // @phpstan-ignore-next-line method.alreadyNarrowedType + $this->assertInstanceOf(MonitorGetLimitsResponse::class, $result); + } + #[Test] public function testListAccountChanges(): void { 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..c0febb0 100644 --- a/tests/Services/WebTest.php +++ b/tests/Services/WebTest.php @@ -82,7 +82,9 @@ public function testExtractWithOptionalParams(): void maxDepth: 0, maxPages: 1, pdf: ['end' => 1, 'shouldParse' => true, 'start' => 1], + settleAnimations: true, stopAfterMs: 10000, + tags: ['production', 'team-alpha'], timeoutMs: 1000, waitForMs: 0, ); @@ -114,7 +116,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 +203,7 @@ public function testSearchWithOptionalParams(): void ], numResults: 10, queryFanout: true, + tags: ['production', 'team-alpha'], timeoutMs: 1000, ); @@ -243,10 +247,12 @@ public function testWebCrawlMdWithOptionalParams(): void settleAnimations: true, shortenBase64Images: true, stopAfterMs: 10000, + tags: ['production', 'team-alpha'], timeoutMs: 1000, urlRegex: '^https?://[^/]+/blog/', useMainContentOnly: true, waitForMs: 0, + zdr: 'enabled', ); // @phpstan-ignore-next-line method.alreadyNarrowedType @@ -275,17 +281,20 @@ public function testWebScrapeHTMLWithOptionalParams(): void $result = $this->client->web->webScrapeHTML( url: 'https://example.com', + actions: [['do' => 'wait', 'timeMs' => 0]], 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, + zdr: 'enabled', ); // @phpstan-ignore-next-line method.alreadyNarrowedType @@ -314,16 +323,18 @@ public function testWebScrapeImagesWithOptionalParams(): void $result = $this->client->web->webScrapeImages( url: 'https://example.com', - dedupe: true, + actions: [['do' => 'wait', 'timeMs' => 0]], + 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, ); @@ -353,20 +364,23 @@ public function testWebScrapeMdWithOptionalParams(): void $result = $this->client->web->webScrapeMd( url: 'https://example.com', + actions: [['do' => 'wait', 'timeMs' => 0]], 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, + zdr: 'enabled', ); // @phpstan-ignore-next-line method.alreadyNarrowedType @@ -380,7 +394,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,11 +408,14 @@ 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/', + zdr: 'enabled', ); // @phpstan-ignore-next-line method.alreadyNarrowedType