diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 4dedeae..511dd51 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "2.5.0" + ".": "2.6.0" } \ No newline at end of file diff --git a/.stats.yml b/.stats.yml index 0ac1eb3..33b7080 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1,4 +1,4 @@ -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 +configured_endpoints: 37 +openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/context-dev/context.dev-960cb623c7ec84bf4dc0f5945cbc19eec9cca48271071f400d96066eaa55dbd6.yml +openapi_spec_hash: 84fd39e3f4dc964bf0c32d4e95da1b34 +config_hash: 2bea1743c84d63bd61f8501a6ea63065 diff --git a/CHANGELOG.md b/CHANGELOG.md index 3a07e8d..8486fec 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,18 @@ # Changelog +## 2.6.0 (2026-07-31) + +Full Changelog: [v2.5.0...v2.6.0](https://github.com/context-dot-dev/context-php-sdk/compare/v2.5.0...v2.6.0) + +### Features + +* **api:** api update ([b59e9c6](https://github.com/context-dot-dev/context-php-sdk/commit/b59e9c6dc3fcfd6009c0446923fd637f4f061cc6)) +* **api:** api update ([dfc48ee](https://github.com/context-dot-dev/context-php-sdk/commit/dfc48eeff2f2d8bcbdbe8943c50fa60621196e30)) +* **api:** api update ([dd8d83a](https://github.com/context-dot-dev/context-php-sdk/commit/dd8d83aebc6aad41b51ce8781ac6608d6ac1c017)) +* **api:** api update ([ead89a6](https://github.com/context-dot-dev/context-php-sdk/commit/ead89a68d802e28bce49e8fbbecd9afbd064abfc)) +* **api:** api update ([61f098d](https://github.com/context-dot-dev/context-php-sdk/commit/61f098d3e54db1a7ed6e927cfd0a4b036ceb97c9)) +* **api:** manual updates ([899b0c9](https://github.com/context-dot-dev/context-php-sdk/commit/899b0c946eb9d92294f5d0b5d3ef2d1c50f8ac20)) + ## 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) diff --git a/README.md b/README.md index ca69c9f..2f5e06f 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.5.0" +composer require "context-dev/context-dev-php 2.6.0" ``` diff --git a/src/Batch/BatchCancelResponse.php b/src/Batch/BatchCancelResponse.php new file mode 100644 index 0000000..f0ea9e0 --- /dev/null +++ b/src/Batch/BatchCancelResponse.php @@ -0,0 +1,398 @@ +, + * input: Input|InputShape, + * mode: Mode|value-of, + * progress: Progress|ProgressShape, + * results: null|Results|ResultsShape, + * status: Status|value-of, + * tags: list, + * timing: Timing|TimingShape, + * type: Type|value-of, + * keyMetadata?: null|KeyMetadata|KeyMetadataShape, + * } + */ +final class BatchCancelResponse implements BaseModel +{ + /** @use SdkModel */ + use SdkModel; + + /** + * Batch ID used to retrieve or cancel the job. + */ + #[Required] + public string $id; + + /** + * Reserved and used credits. + */ + #[Required] + public Credits $credits; + + /** + * Why the batch failed. + */ + #[Required] + public ?Error $error; + + /** + * Page failures grouped by error code. + * + * @var list $errors + */ + #[Required(list: ErrorCount::class)] + public array $errors; + + /** + * Submission counts. + */ + #[Required] + public Input $input; + + /** + * How pages are selected. + * + * @var value-of $mode + */ + #[Required(enum: Mode::class)] + public string $mode; + + /** + * Current processing counts. Use `status` to check completion. + */ + #[Required] + public Progress $progress; + + /** + * Download links available when the batch finishes. GET /batch/{batch_id}/results serves the same records as paginated JSON. + */ + #[Required] + public ?Results $results; + + /** + * Current state. `completed`, `cancelled`, and `failed` are final. + * + * @var value-of $status + */ + #[Required(enum: Status::class)] + public string $status; + + /** + * Tags stored on the batch at submission. + * + * @var list $tags + */ + #[Required(list: 'string')] + public array $tags; + + #[Required] + public Timing $timing; + + /** + * Output format. + * + * @var value-of $type + */ + #[Required(enum: Type::class)] + public string $type; + + /** + * API key usage for this request. + */ + #[Optional('key_metadata')] + public ?KeyMetadata $keyMetadata; + + /** + * `new BatchCancelResponse()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * BatchCancelResponse::with( + * id: ..., + * credits: ..., + * error: ..., + * errors: ..., + * input: ..., + * mode: ..., + * progress: ..., + * results: ..., + * status: ..., + * tags: ..., + * timing: ..., + * type: ..., + * ) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new BatchCancelResponse) + * ->withID(...) + * ->withCredits(...) + * ->withError(...) + * ->withErrors(...) + * ->withInput(...) + * ->withMode(...) + * ->withProgress(...) + * ->withResults(...) + * ->withStatus(...) + * ->withTags(...) + * ->withTiming(...) + * ->withType(...) + * ``` + */ + 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 Credits|CreditsShape $credits + * @param Error|ErrorShape|null $error + * @param list $errors + * @param Input|InputShape $input + * @param Mode|value-of $mode + * @param Progress|ProgressShape $progress + * @param Results|ResultsShape|null $results + * @param Status|value-of $status + * @param list $tags + * @param Timing|TimingShape $timing + * @param Type|value-of $type + * @param KeyMetadata|KeyMetadataShape|null $keyMetadata + */ + public static function with( + string $id, + Credits|array $credits, + Error|array|null $error, + array $errors, + Input|array $input, + Mode|string $mode, + Progress|array $progress, + Results|array|null $results, + Status|string $status, + array $tags, + Timing|array $timing, + Type|string $type, + KeyMetadata|array|null $keyMetadata = null, + ): self { + $self = new self; + + $self['id'] = $id; + $self['credits'] = $credits; + $self['error'] = $error; + $self['errors'] = $errors; + $self['input'] = $input; + $self['mode'] = $mode; + $self['progress'] = $progress; + $self['results'] = $results; + $self['status'] = $status; + $self['tags'] = $tags; + $self['timing'] = $timing; + $self['type'] = $type; + + null !== $keyMetadata && $self['keyMetadata'] = $keyMetadata; + + return $self; + } + + /** + * Batch ID used to retrieve or cancel the job. + */ + public function withID(string $id): self + { + $self = clone $this; + $self['id'] = $id; + + return $self; + } + + /** + * Reserved and used credits. + * + * @param Credits|CreditsShape $credits + */ + public function withCredits(Credits|array $credits): self + { + $self = clone $this; + $self['credits'] = $credits; + + return $self; + } + + /** + * Why the batch failed. + * + * @param Error|ErrorShape|null $error + */ + public function withError(Error|array|null $error): self + { + $self = clone $this; + $self['error'] = $error; + + return $self; + } + + /** + * Page failures grouped by error code. + * + * @param list $errors + */ + public function withErrors(array $errors): self + { + $self = clone $this; + $self['errors'] = $errors; + + return $self; + } + + /** + * Submission counts. + * + * @param Input|InputShape $input + */ + public function withInput(Input|array $input): self + { + $self = clone $this; + $self['input'] = $input; + + return $self; + } + + /** + * How pages are selected. + * + * @param Mode|value-of $mode + */ + public function withMode(Mode|string $mode): self + { + $self = clone $this; + $self['mode'] = $mode; + + return $self; + } + + /** + * Current processing counts. Use `status` to check completion. + * + * @param Progress|ProgressShape $progress + */ + public function withProgress(Progress|array $progress): self + { + $self = clone $this; + $self['progress'] = $progress; + + return $self; + } + + /** + * Download links available when the batch finishes. GET /batch/{batch_id}/results serves the same records as paginated JSON. + * + * @param Results|ResultsShape|null $results + */ + public function withResults(Results|array|null $results): self + { + $self = clone $this; + $self['results'] = $results; + + return $self; + } + + /** + * Current state. `completed`, `cancelled`, and `failed` are final. + * + * @param Status|value-of $status + */ + public function withStatus(Status|string $status): self + { + $self = clone $this; + $self['status'] = $status; + + return $self; + } + + /** + * Tags stored on the batch at submission. + * + * @param list $tags + */ + public function withTags(array $tags): self + { + $self = clone $this; + $self['tags'] = $tags; + + return $self; + } + + /** + * @param Timing|TimingShape $timing + */ + public function withTiming(Timing|array $timing): self + { + $self = clone $this; + $self['timing'] = $timing; + + return $self; + } + + /** + * Output format. + * + * @param Type|value-of $type + */ + public function withType(Type|string $type): self + { + $self = clone $this; + $self['type'] = $type; + + return $self; + } + + /** + * API key usage for this request. + * + * @param KeyMetadata|KeyMetadataShape $keyMetadata + */ + public function withKeyMetadata(KeyMetadata|array $keyMetadata): self + { + $self = clone $this; + $self['keyMetadata'] = $keyMetadata; + + return $self; + } +} diff --git a/src/Batch/BatchCancelResponse/Credits.php b/src/Batch/BatchCancelResponse/Credits.php new file mode 100644 index 0000000..6484e73 --- /dev/null +++ b/src/Batch/BatchCancelResponse/Credits.php @@ -0,0 +1,88 @@ + */ + use SdkModel; + + /** + * Credits used by successful pages. + */ + #[Required] + public int $charged; + + /** + * Credits reserved when the batch was accepted. + */ + #[Required] + public int $estimated; + + /** + * `new Credits()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * Credits::with(charged: ..., estimated: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new Credits)->withCharged(...)->withEstimated(...) + * ``` + */ + 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 $charged, int $estimated): self + { + $self = new self; + + $self['charged'] = $charged; + $self['estimated'] = $estimated; + + return $self; + } + + /** + * Credits used by successful pages. + */ + public function withCharged(int $charged): self + { + $self = clone $this; + $self['charged'] = $charged; + + return $self; + } + + /** + * Credits reserved when the batch was accepted. + */ + public function withEstimated(int $estimated): self + { + $self = clone $this; + $self['estimated'] = $estimated; + + return $self; + } +} diff --git a/src/Batch/BatchCancelResponse/Input.php b/src/Batch/BatchCancelResponse/Input.php new file mode 100644 index 0000000..684dc94 --- /dev/null +++ b/src/Batch/BatchCancelResponse/Input.php @@ -0,0 +1,134 @@ + */ + use SdkModel; + + /** + * Pages accepted, or the crawl page limit. Credits are reserved for this count. + */ + #[Required] + public int $accepted; + + /** + * Duplicate URL and `itemId` pairs skipped. Always 0 for crawls. + */ + #[Required] + public int $duplicates; + + /** + * Pages rejected during validation. + */ + #[Required] + public int $invalid; + + /** + * Pages submitted before validation. For a crawl, the page limit. + */ + #[Required] + public int $submitted; + + /** + * `new Input()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * Input::with(accepted: ..., duplicates: ..., invalid: ..., submitted: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new Input) + * ->withAccepted(...) + * ->withDuplicates(...) + * ->withInvalid(...) + * ->withSubmitted(...) + * ``` + */ + 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 $accepted, + int $duplicates, + int $invalid, + int $submitted + ): self { + $self = new self; + + $self['accepted'] = $accepted; + $self['duplicates'] = $duplicates; + $self['invalid'] = $invalid; + $self['submitted'] = $submitted; + + return $self; + } + + /** + * Pages accepted, or the crawl page limit. Credits are reserved for this count. + */ + public function withAccepted(int $accepted): self + { + $self = clone $this; + $self['accepted'] = $accepted; + + return $self; + } + + /** + * Duplicate URL and `itemId` pairs skipped. Always 0 for crawls. + */ + public function withDuplicates(int $duplicates): self + { + $self = clone $this; + $self['duplicates'] = $duplicates; + + return $self; + } + + /** + * Pages rejected during validation. + */ + public function withInvalid(int $invalid): self + { + $self = clone $this; + $self['invalid'] = $invalid; + + return $self; + } + + /** + * Pages submitted before validation. For a crawl, the page limit. + */ + public function withSubmitted(int $submitted): self + { + $self = clone $this; + $self['submitted'] = $submitted; + + return $self; + } +} diff --git a/src/Batch/BatchCancelResponse/KeyMetadata.php b/src/Batch/BatchCancelResponse/KeyMetadata.php new file mode 100644 index 0000000..f072b09 --- /dev/null +++ b/src/Batch/BatchCancelResponse/KeyMetadata.php @@ -0,0 +1,92 @@ + */ + use SdkModel; + + /** + * The number of credits consumed by this request. + */ + #[Required('credits_consumed')] + public int $creditsConsumed; + + /** + * The number of credits remaining for your organization after this request. + */ + #[Required('credits_remaining')] + public int $creditsRemaining; + + /** + * `new KeyMetadata()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * KeyMetadata::with(creditsConsumed: ..., creditsRemaining: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new KeyMetadata)->withCreditsConsumed(...)->withCreditsRemaining(...) + * ``` + */ + 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 $creditsConsumed, + int $creditsRemaining + ): self { + $self = new self; + + $self['creditsConsumed'] = $creditsConsumed; + $self['creditsRemaining'] = $creditsRemaining; + + return $self; + } + + /** + * The number of credits consumed by this request. + */ + public function withCreditsConsumed(int $creditsConsumed): self + { + $self = clone $this; + $self['creditsConsumed'] = $creditsConsumed; + + return $self; + } + + /** + * The number of credits remaining for your organization after this request. + */ + public function withCreditsRemaining(int $creditsRemaining): self + { + $self = clone $this; + $self['creditsRemaining'] = $creditsRemaining; + + return $self; + } +} diff --git a/src/Batch/BatchCancelResponse/Mode.php b/src/Batch/BatchCancelResponse/Mode.php new file mode 100644 index 0000000..c530dfa --- /dev/null +++ b/src/Batch/BatchCancelResponse/Mode.php @@ -0,0 +1,15 @@ + */ + use SdkModel; + + /** + * Pages that could not be scraped. + */ + #[Required] + public int $failed; + + /** + * Accepted pages not yet attempted. Always 0 once the batch completes; a crawl can finish under its page limit when the site has no more reachable pages. + */ + #[Required] + public int $pending; + + /** + * Pages scraped successfully. + */ + #[Required] + public int $succeeded; + + /** + * `new Progress()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * Progress::with(failed: ..., pending: ..., succeeded: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new Progress)->withFailed(...)->withPending(...)->withSucceeded(...) + * ``` + */ + 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 $failed, int $pending, int $succeeded): self + { + $self = new self; + + $self['failed'] = $failed; + $self['pending'] = $pending; + $self['succeeded'] = $succeeded; + + return $self; + } + + /** + * Pages that could not be scraped. + */ + public function withFailed(int $failed): self + { + $self = clone $this; + $self['failed'] = $failed; + + return $self; + } + + /** + * Accepted pages not yet attempted. Always 0 once the batch completes; a crawl can finish under its page limit when the site has no more reachable pages. + */ + public function withPending(int $pending): self + { + $self = clone $this; + $self['pending'] = $pending; + + return $self; + } + + /** + * Pages scraped successfully. + */ + public function withSucceeded(int $succeeded): self + { + $self = clone $this; + $self['succeeded'] = $succeeded; + + return $self; + } +} diff --git a/src/Batch/BatchCancelResponse/Results.php b/src/Batch/BatchCancelResponse/Results.php new file mode 100644 index 0000000..f28b3d3 --- /dev/null +++ b/src/Batch/BatchCancelResponse/Results.php @@ -0,0 +1,99 @@ + + * } + */ +final class Results implements BaseModel +{ + /** @use SdkModel */ + use SdkModel; + + /** + * When the download URLs expire. + */ + #[Required('expires_at')] + public string $expiresAt; + + /** + * Result files. Order is not guaranteed. + * + * @var list $files + */ + #[Required(list: File::class)] + public array $files; + + /** + * `new Results()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * Results::with(expiresAt: ..., files: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new Results)->withExpiresAt(...)->withFiles(...) + * ``` + */ + 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 $files + */ + public static function with(string $expiresAt, array $files): self + { + $self = new self; + + $self['expiresAt'] = $expiresAt; + $self['files'] = $files; + + return $self; + } + + /** + * When the download URLs expire. + */ + public function withExpiresAt(string $expiresAt): self + { + $self = clone $this; + $self['expiresAt'] = $expiresAt; + + return $self; + } + + /** + * Result files. Order is not guaranteed. + * + * @param list $files + */ + public function withFiles(array $files): self + { + $self = clone $this; + $self['files'] = $files; + + return $self; + } +} diff --git a/src/Batch/BatchCancelResponse/Results/File.php b/src/Batch/BatchCancelResponse/Results/File.php new file mode 100644 index 0000000..0867a93 --- /dev/null +++ b/src/Batch/BatchCancelResponse/Results/File.php @@ -0,0 +1,104 @@ + */ + use SdkModel; + + /** + * Compressed file size in bytes. + */ + #[Required] + public int $bytes; + + /** + * Results in this file. + */ + #[Required] + public int $items; + + /** + * Temporary URL for a gzipped NDJSON file. + */ + #[Required] + public string $url; + + /** + * `new File()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * File::with(bytes: ..., items: ..., url: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new File)->withBytes(...)->withItems(...)->withURL(...) + * ``` + */ + 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 $bytes, int $items, string $url): self + { + $self = new self; + + $self['bytes'] = $bytes; + $self['items'] = $items; + $self['url'] = $url; + + return $self; + } + + /** + * Compressed file size in bytes. + */ + public function withBytes(int $bytes): self + { + $self = clone $this; + $self['bytes'] = $bytes; + + return $self; + } + + /** + * Results in this file. + */ + public function withItems(int $items): self + { + $self = clone $this; + $self['items'] = $items; + + return $self; + } + + /** + * Temporary URL for a gzipped NDJSON file. + */ + public function withURL(string $url): self + { + $self = clone $this; + $self['url'] = $url; + + return $self; + } +} diff --git a/src/Batch/BatchCancelResponse/Status.php b/src/Batch/BatchCancelResponse/Status.php new file mode 100644 index 0000000..01a1e5a --- /dev/null +++ b/src/Batch/BatchCancelResponse/Status.php @@ -0,0 +1,23 @@ + */ + use SdkModel; + + /** + * When processing finished. Null while active. + */ + #[Required('completed_at')] + public ?string $completedAt; + + /** + * When the batch was created. + */ + #[Required('created_at')] + public string $createdAt; + + /** + * When processing started. Null while queued. + */ + #[Required('started_at')] + public ?string $startedAt; + + /** + * `new Timing()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * Timing::with(completedAt: ..., createdAt: ..., startedAt: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new Timing)->withCompletedAt(...)->withCreatedAt(...)->withStartedAt(...) + * ``` + */ + 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 $completedAt, + string $createdAt, + ?string $startedAt + ): self { + $self = new self; + + $self['completedAt'] = $completedAt; + $self['createdAt'] = $createdAt; + $self['startedAt'] = $startedAt; + + return $self; + } + + /** + * When processing finished. Null while active. + */ + public function withCompletedAt(?string $completedAt): self + { + $self = clone $this; + $self['completedAt'] = $completedAt; + + return $self; + } + + /** + * When the batch was created. + */ + public function withCreatedAt(string $createdAt): self + { + $self = clone $this; + $self['createdAt'] = $createdAt; + + return $self; + } + + /** + * When processing started. Null while queued. + */ + public function withStartedAt(?string $startedAt): self + { + $self = clone $this; + $self['startedAt'] = $startedAt; + + return $self; + } +} diff --git a/src/Batch/BatchCancelResponse/Type.php b/src/Batch/BatchCancelResponse/Type.php new file mode 100644 index 0000000..30a60b2 --- /dev/null +++ b/src/Batch/BatchCancelResponse/Type.php @@ -0,0 +1,15 @@ +, + * input: Input|InputShape, + * invalidURLs: list, + * mode: Mode|value-of, + * progress: Progress|ProgressShape, + * results: null|Results|ResultsShape, + * status: Status|value-of, + * tags: list, + * timing: Timing|TimingShape, + * type: Type|value-of, + * keyMetadata?: null|KeyMetadata|KeyMetadataShape, + * webhookSecret?: string|null, + * } + */ +final class BatchGetResponse implements BaseModel +{ + /** @use SdkModel */ + use SdkModel; + + /** + * Batch ID used to retrieve or cancel the job. + */ + #[Required] + public string $id; + + /** + * Reserved and used credits. + */ + #[Required] + public Credits $credits; + + /** + * Why the batch failed. + */ + #[Required] + public ?Error $error; + + /** + * Page failures grouped by error code. + * + * @var list $errors + */ + #[Required(list: ErrorCount::class)] + public array $errors; + + /** + * Submission counts. + */ + #[Required] + public Input $input; + + /** + * Rejected URLs, up to 100. These are not charged. + * + * @var list $invalidURLs + */ + #[Required('invalid_urls', list: InvalidURL::class)] + public array $invalidURLs; + + /** + * How pages are selected. + * + * @var value-of $mode + */ + #[Required(enum: Mode::class)] + public string $mode; + + /** + * Current processing counts. Use `status` to check completion. + */ + #[Required] + public Progress $progress; + + /** + * Download links available when the batch finishes. GET /batch/{batch_id}/results serves the same records as paginated JSON. + */ + #[Required] + public ?Results $results; + + /** + * Current state. `completed`, `cancelled`, and `failed` are final. + * + * @var value-of $status + */ + #[Required(enum: Status::class)] + public string $status; + + /** + * Tags stored on the batch at submission. + * + * @var list $tags + */ + #[Required(list: 'string')] + public array $tags; + + #[Required] + public Timing $timing; + + /** + * Output format. + * + * @var value-of $type + */ + #[Required(enum: Type::class)] + public string $type; + + /** + * API key usage for this request. + */ + #[Optional('key_metadata')] + public ?KeyMetadata $keyMetadata; + + /** + * Webhook signing secret. Also returned by GET /batch/{batch_id}. + */ + #[Optional('webhook_secret')] + public ?string $webhookSecret; + + /** + * `new BatchGetResponse()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * BatchGetResponse::with( + * id: ..., + * credits: ..., + * error: ..., + * errors: ..., + * input: ..., + * invalidURLs: ..., + * mode: ..., + * progress: ..., + * results: ..., + * status: ..., + * tags: ..., + * timing: ..., + * type: ..., + * ) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new BatchGetResponse) + * ->withID(...) + * ->withCredits(...) + * ->withError(...) + * ->withErrors(...) + * ->withInput(...) + * ->withInvalidURLs(...) + * ->withMode(...) + * ->withProgress(...) + * ->withResults(...) + * ->withStatus(...) + * ->withTags(...) + * ->withTiming(...) + * ->withType(...) + * ``` + */ + 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 Credits|CreditsShape $credits + * @param Error|ErrorShape|null $error + * @param list $errors + * @param Input|InputShape $input + * @param list $invalidURLs + * @param Mode|value-of $mode + * @param Progress|ProgressShape $progress + * @param Results|ResultsShape|null $results + * @param Status|value-of $status + * @param list $tags + * @param Timing|TimingShape $timing + * @param Type|value-of $type + * @param KeyMetadata|KeyMetadataShape|null $keyMetadata + */ + public static function with( + string $id, + Credits|array $credits, + Error|array|null $error, + array $errors, + Input|array $input, + array $invalidURLs, + Mode|string $mode, + Progress|array $progress, + Results|array|null $results, + Status|string $status, + array $tags, + Timing|array $timing, + Type|string $type, + KeyMetadata|array|null $keyMetadata = null, + ?string $webhookSecret = null, + ): self { + $self = new self; + + $self['id'] = $id; + $self['credits'] = $credits; + $self['error'] = $error; + $self['errors'] = $errors; + $self['input'] = $input; + $self['invalidURLs'] = $invalidURLs; + $self['mode'] = $mode; + $self['progress'] = $progress; + $self['results'] = $results; + $self['status'] = $status; + $self['tags'] = $tags; + $self['timing'] = $timing; + $self['type'] = $type; + + null !== $keyMetadata && $self['keyMetadata'] = $keyMetadata; + null !== $webhookSecret && $self['webhookSecret'] = $webhookSecret; + + return $self; + } + + /** + * Batch ID used to retrieve or cancel the job. + */ + public function withID(string $id): self + { + $self = clone $this; + $self['id'] = $id; + + return $self; + } + + /** + * Reserved and used credits. + * + * @param Credits|CreditsShape $credits + */ + public function withCredits(Credits|array $credits): self + { + $self = clone $this; + $self['credits'] = $credits; + + return $self; + } + + /** + * Why the batch failed. + * + * @param Error|ErrorShape|null $error + */ + public function withError(Error|array|null $error): self + { + $self = clone $this; + $self['error'] = $error; + + return $self; + } + + /** + * Page failures grouped by error code. + * + * @param list $errors + */ + public function withErrors(array $errors): self + { + $self = clone $this; + $self['errors'] = $errors; + + return $self; + } + + /** + * Submission counts. + * + * @param Input|InputShape $input + */ + public function withInput(Input|array $input): self + { + $self = clone $this; + $self['input'] = $input; + + return $self; + } + + /** + * Rejected URLs, up to 100. These are not charged. + * + * @param list $invalidURLs + */ + public function withInvalidURLs(array $invalidURLs): self + { + $self = clone $this; + $self['invalidURLs'] = $invalidURLs; + + return $self; + } + + /** + * How pages are selected. + * + * @param Mode|value-of $mode + */ + public function withMode(Mode|string $mode): self + { + $self = clone $this; + $self['mode'] = $mode; + + return $self; + } + + /** + * Current processing counts. Use `status` to check completion. + * + * @param Progress|ProgressShape $progress + */ + public function withProgress(Progress|array $progress): self + { + $self = clone $this; + $self['progress'] = $progress; + + return $self; + } + + /** + * Download links available when the batch finishes. GET /batch/{batch_id}/results serves the same records as paginated JSON. + * + * @param Results|ResultsShape|null $results + */ + public function withResults(Results|array|null $results): self + { + $self = clone $this; + $self['results'] = $results; + + return $self; + } + + /** + * Current state. `completed`, `cancelled`, and `failed` are final. + * + * @param Status|value-of $status + */ + public function withStatus(Status|string $status): self + { + $self = clone $this; + $self['status'] = $status; + + return $self; + } + + /** + * Tags stored on the batch at submission. + * + * @param list $tags + */ + public function withTags(array $tags): self + { + $self = clone $this; + $self['tags'] = $tags; + + return $self; + } + + /** + * @param Timing|TimingShape $timing + */ + public function withTiming(Timing|array $timing): self + { + $self = clone $this; + $self['timing'] = $timing; + + return $self; + } + + /** + * Output format. + * + * @param Type|value-of $type + */ + public function withType(Type|string $type): self + { + $self = clone $this; + $self['type'] = $type; + + return $self; + } + + /** + * API key usage for this request. + * + * @param KeyMetadata|KeyMetadataShape $keyMetadata + */ + public function withKeyMetadata(KeyMetadata|array $keyMetadata): self + { + $self = clone $this; + $self['keyMetadata'] = $keyMetadata; + + return $self; + } + + /** + * Webhook signing secret. Also returned by GET /batch/{batch_id}. + */ + public function withWebhookSecret(string $webhookSecret): self + { + $self = clone $this; + $self['webhookSecret'] = $webhookSecret; + + return $self; + } +} diff --git a/src/Batch/BatchGetResponse/Credits.php b/src/Batch/BatchGetResponse/Credits.php new file mode 100644 index 0000000..5014503 --- /dev/null +++ b/src/Batch/BatchGetResponse/Credits.php @@ -0,0 +1,88 @@ + */ + use SdkModel; + + /** + * Credits used by successful pages. + */ + #[Required] + public int $charged; + + /** + * Credits reserved when the batch was accepted. + */ + #[Required] + public int $estimated; + + /** + * `new Credits()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * Credits::with(charged: ..., estimated: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new Credits)->withCharged(...)->withEstimated(...) + * ``` + */ + 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 $charged, int $estimated): self + { + $self = new self; + + $self['charged'] = $charged; + $self['estimated'] = $estimated; + + return $self; + } + + /** + * Credits used by successful pages. + */ + public function withCharged(int $charged): self + { + $self = clone $this; + $self['charged'] = $charged; + + return $self; + } + + /** + * Credits reserved when the batch was accepted. + */ + public function withEstimated(int $estimated): self + { + $self = clone $this; + $self['estimated'] = $estimated; + + return $self; + } +} diff --git a/src/Batch/BatchGetResponse/Input.php b/src/Batch/BatchGetResponse/Input.php new file mode 100644 index 0000000..84c30d0 --- /dev/null +++ b/src/Batch/BatchGetResponse/Input.php @@ -0,0 +1,134 @@ + */ + use SdkModel; + + /** + * Pages accepted, or the crawl page limit. Credits are reserved for this count. + */ + #[Required] + public int $accepted; + + /** + * Duplicate URL and `itemId` pairs skipped. Always 0 for crawls. + */ + #[Required] + public int $duplicates; + + /** + * Pages rejected during validation. + */ + #[Required] + public int $invalid; + + /** + * Pages submitted before validation. For a crawl, the page limit. + */ + #[Required] + public int $submitted; + + /** + * `new Input()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * Input::with(accepted: ..., duplicates: ..., invalid: ..., submitted: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new Input) + * ->withAccepted(...) + * ->withDuplicates(...) + * ->withInvalid(...) + * ->withSubmitted(...) + * ``` + */ + 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 $accepted, + int $duplicates, + int $invalid, + int $submitted + ): self { + $self = new self; + + $self['accepted'] = $accepted; + $self['duplicates'] = $duplicates; + $self['invalid'] = $invalid; + $self['submitted'] = $submitted; + + return $self; + } + + /** + * Pages accepted, or the crawl page limit. Credits are reserved for this count. + */ + public function withAccepted(int $accepted): self + { + $self = clone $this; + $self['accepted'] = $accepted; + + return $self; + } + + /** + * Duplicate URL and `itemId` pairs skipped. Always 0 for crawls. + */ + public function withDuplicates(int $duplicates): self + { + $self = clone $this; + $self['duplicates'] = $duplicates; + + return $self; + } + + /** + * Pages rejected during validation. + */ + public function withInvalid(int $invalid): self + { + $self = clone $this; + $self['invalid'] = $invalid; + + return $self; + } + + /** + * Pages submitted before validation. For a crawl, the page limit. + */ + public function withSubmitted(int $submitted): self + { + $self = clone $this; + $self['submitted'] = $submitted; + + return $self; + } +} diff --git a/src/Batch/BatchGetResponse/InvalidURL.php b/src/Batch/BatchGetResponse/InvalidURL.php new file mode 100644 index 0000000..dd103b2 --- /dev/null +++ b/src/Batch/BatchGetResponse/InvalidURL.php @@ -0,0 +1,86 @@ + */ + use SdkModel; + + /** + * Why it was rejected. + */ + #[Required] + public string $reason; + + /** + * Rejected URL. + */ + #[Required] + public string $url; + + /** + * `new InvalidURL()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * InvalidURL::with(reason: ..., url: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new InvalidURL)->withReason(...)->withURL(...) + * ``` + */ + 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 $reason, string $url): self + { + $self = new self; + + $self['reason'] = $reason; + $self['url'] = $url; + + return $self; + } + + /** + * Why it was rejected. + */ + public function withReason(string $reason): self + { + $self = clone $this; + $self['reason'] = $reason; + + return $self; + } + + /** + * Rejected URL. + */ + public function withURL(string $url): self + { + $self = clone $this; + $self['url'] = $url; + + return $self; + } +} diff --git a/src/Batch/BatchGetResponse/KeyMetadata.php b/src/Batch/BatchGetResponse/KeyMetadata.php new file mode 100644 index 0000000..77c3861 --- /dev/null +++ b/src/Batch/BatchGetResponse/KeyMetadata.php @@ -0,0 +1,92 @@ + */ + use SdkModel; + + /** + * The number of credits consumed by this request. + */ + #[Required('credits_consumed')] + public int $creditsConsumed; + + /** + * The number of credits remaining for your organization after this request. + */ + #[Required('credits_remaining')] + public int $creditsRemaining; + + /** + * `new KeyMetadata()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * KeyMetadata::with(creditsConsumed: ..., creditsRemaining: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new KeyMetadata)->withCreditsConsumed(...)->withCreditsRemaining(...) + * ``` + */ + 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 $creditsConsumed, + int $creditsRemaining + ): self { + $self = new self; + + $self['creditsConsumed'] = $creditsConsumed; + $self['creditsRemaining'] = $creditsRemaining; + + return $self; + } + + /** + * The number of credits consumed by this request. + */ + public function withCreditsConsumed(int $creditsConsumed): self + { + $self = clone $this; + $self['creditsConsumed'] = $creditsConsumed; + + return $self; + } + + /** + * The number of credits remaining for your organization after this request. + */ + public function withCreditsRemaining(int $creditsRemaining): self + { + $self = clone $this; + $self['creditsRemaining'] = $creditsRemaining; + + return $self; + } +} diff --git a/src/Batch/BatchGetResponse/Mode.php b/src/Batch/BatchGetResponse/Mode.php new file mode 100644 index 0000000..78ded37 --- /dev/null +++ b/src/Batch/BatchGetResponse/Mode.php @@ -0,0 +1,15 @@ + */ + use SdkModel; + + /** + * Pages that could not be scraped. + */ + #[Required] + public int $failed; + + /** + * Accepted pages not yet attempted. Always 0 once the batch completes; a crawl can finish under its page limit when the site has no more reachable pages. + */ + #[Required] + public int $pending; + + /** + * Pages scraped successfully. + */ + #[Required] + public int $succeeded; + + /** + * `new Progress()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * Progress::with(failed: ..., pending: ..., succeeded: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new Progress)->withFailed(...)->withPending(...)->withSucceeded(...) + * ``` + */ + 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 $failed, int $pending, int $succeeded): self + { + $self = new self; + + $self['failed'] = $failed; + $self['pending'] = $pending; + $self['succeeded'] = $succeeded; + + return $self; + } + + /** + * Pages that could not be scraped. + */ + public function withFailed(int $failed): self + { + $self = clone $this; + $self['failed'] = $failed; + + return $self; + } + + /** + * Accepted pages not yet attempted. Always 0 once the batch completes; a crawl can finish under its page limit when the site has no more reachable pages. + */ + public function withPending(int $pending): self + { + $self = clone $this; + $self['pending'] = $pending; + + return $self; + } + + /** + * Pages scraped successfully. + */ + public function withSucceeded(int $succeeded): self + { + $self = clone $this; + $self['succeeded'] = $succeeded; + + return $self; + } +} diff --git a/src/Batch/BatchGetResponse/Results.php b/src/Batch/BatchGetResponse/Results.php new file mode 100644 index 0000000..a91153c --- /dev/null +++ b/src/Batch/BatchGetResponse/Results.php @@ -0,0 +1,99 @@ + + * } + */ +final class Results implements BaseModel +{ + /** @use SdkModel */ + use SdkModel; + + /** + * When the download URLs expire. + */ + #[Required('expires_at')] + public string $expiresAt; + + /** + * Result files. Order is not guaranteed. + * + * @var list $files + */ + #[Required(list: File::class)] + public array $files; + + /** + * `new Results()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * Results::with(expiresAt: ..., files: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new Results)->withExpiresAt(...)->withFiles(...) + * ``` + */ + 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 $files + */ + public static function with(string $expiresAt, array $files): self + { + $self = new self; + + $self['expiresAt'] = $expiresAt; + $self['files'] = $files; + + return $self; + } + + /** + * When the download URLs expire. + */ + public function withExpiresAt(string $expiresAt): self + { + $self = clone $this; + $self['expiresAt'] = $expiresAt; + + return $self; + } + + /** + * Result files. Order is not guaranteed. + * + * @param list $files + */ + public function withFiles(array $files): self + { + $self = clone $this; + $self['files'] = $files; + + return $self; + } +} diff --git a/src/Batch/BatchGetResponse/Results/File.php b/src/Batch/BatchGetResponse/Results/File.php new file mode 100644 index 0000000..019b67b --- /dev/null +++ b/src/Batch/BatchGetResponse/Results/File.php @@ -0,0 +1,104 @@ + */ + use SdkModel; + + /** + * Compressed file size in bytes. + */ + #[Required] + public int $bytes; + + /** + * Results in this file. + */ + #[Required] + public int $items; + + /** + * Temporary URL for a gzipped NDJSON file. + */ + #[Required] + public string $url; + + /** + * `new File()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * File::with(bytes: ..., items: ..., url: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new File)->withBytes(...)->withItems(...)->withURL(...) + * ``` + */ + 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 $bytes, int $items, string $url): self + { + $self = new self; + + $self['bytes'] = $bytes; + $self['items'] = $items; + $self['url'] = $url; + + return $self; + } + + /** + * Compressed file size in bytes. + */ + public function withBytes(int $bytes): self + { + $self = clone $this; + $self['bytes'] = $bytes; + + return $self; + } + + /** + * Results in this file. + */ + public function withItems(int $items): self + { + $self = clone $this; + $self['items'] = $items; + + return $self; + } + + /** + * Temporary URL for a gzipped NDJSON file. + */ + public function withURL(string $url): self + { + $self = clone $this; + $self['url'] = $url; + + return $self; + } +} diff --git a/src/Batch/BatchGetResponse/Status.php b/src/Batch/BatchGetResponse/Status.php new file mode 100644 index 0000000..fba2606 --- /dev/null +++ b/src/Batch/BatchGetResponse/Status.php @@ -0,0 +1,23 @@ + */ + use SdkModel; + + /** + * When processing finished. Null while active. + */ + #[Required('completed_at')] + public ?string $completedAt; + + /** + * When the batch was created. + */ + #[Required('created_at')] + public string $createdAt; + + /** + * When processing started. Null while queued. + */ + #[Required('started_at')] + public ?string $startedAt; + + /** + * `new Timing()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * Timing::with(completedAt: ..., createdAt: ..., startedAt: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new Timing)->withCompletedAt(...)->withCreatedAt(...)->withStartedAt(...) + * ``` + */ + 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 $completedAt, + string $createdAt, + ?string $startedAt + ): self { + $self = new self; + + $self['completedAt'] = $completedAt; + $self['createdAt'] = $createdAt; + $self['startedAt'] = $startedAt; + + return $self; + } + + /** + * When processing finished. Null while active. + */ + public function withCompletedAt(?string $completedAt): self + { + $self = clone $this; + $self['completedAt'] = $completedAt; + + return $self; + } + + /** + * When the batch was created. + */ + public function withCreatedAt(string $createdAt): self + { + $self = clone $this; + $self['createdAt'] = $createdAt; + + return $self; + } + + /** + * When processing started. Null while queued. + */ + public function withStartedAt(?string $startedAt): self + { + $self = clone $this; + $self['startedAt'] = $startedAt; + + return $self; + } +} diff --git a/src/Batch/BatchGetResponse/Type.php b/src/Batch/BatchGetResponse/Type.php new file mode 100644 index 0000000..def0a61 --- /dev/null +++ b/src/Batch/BatchGetResponse/Type.php @@ -0,0 +1,15 @@ + */ + use SdkModel; + use SdkParams; + + /** + * next_cursor from the previous page. + */ + #[Optional] + public ?string $cursor; + + /** + * Records per page. Defaults to 25. A page can close early so its payload stays under ~8 MB; rely on next_cursor rather than counting records. + */ + #[Optional] + public ?int $limit; + + 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 $cursor = null, ?int $limit = null): self + { + $self = new self; + + null !== $cursor && $self['cursor'] = $cursor; + null !== $limit && $self['limit'] = $limit; + + return $self; + } + + /** + * next_cursor from the previous page. + */ + public function withCursor(string $cursor): self + { + $self = clone $this; + $self['cursor'] = $cursor; + + return $self; + } + + /** + * Records per page. Defaults to 25. A page can close early so its payload stays under ~8 MB; rely on next_cursor rather than counting records. + */ + public function withLimit(int $limit): self + { + $self = clone $this; + $self['limit'] = $limit; + + return $self; + } +} diff --git a/src/Batch/BatchGetResultsResponse.php b/src/Batch/BatchGetResultsResponse.php new file mode 100644 index 0000000..7f81692 --- /dev/null +++ b/src/Batch/BatchGetResultsResponse.php @@ -0,0 +1,132 @@ +|null, + * hasMore?: bool|null, + * keyMetadata?: null|KeyMetadata|KeyMetadataShape, + * nextCursor?: string|null, + * } + */ +final class BatchGetResultsResponse implements BaseModel +{ + /** @use SdkModel */ + use SdkModel; + + /** + * Result records on this page. + * + * @var list|null $data + */ + #[Optional(list: Data::class)] + public ?array $data; + + /** + * Whether another page is available. + */ + #[Optional('has_more')] + public ?bool $hasMore; + + /** + * Metadata about the API key used for the request. Included in every response whenever a valid API key is provided, even when the response status is not 200. + */ + #[Optional('key_metadata')] + public ?KeyMetadata $keyMetadata; + + /** + * Cursor for the next page. + */ + #[Optional('next_cursor', nullable: true)] + public ?string $nextCursor; + + 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|null $data + * @param KeyMetadata|KeyMetadataShape|null $keyMetadata + */ + public static function with( + ?array $data = null, + ?bool $hasMore = null, + KeyMetadata|array|null $keyMetadata = null, + ?string $nextCursor = null, + ): self { + $self = new self; + + null !== $data && $self['data'] = $data; + null !== $hasMore && $self['hasMore'] = $hasMore; + null !== $keyMetadata && $self['keyMetadata'] = $keyMetadata; + null !== $nextCursor && $self['nextCursor'] = $nextCursor; + + return $self; + } + + /** + * Result records on this page. + * + * @param list $data + */ + public function withData(array $data): self + { + $self = clone $this; + $self['data'] = $data; + + return $self; + } + + /** + * Whether another page is available. + */ + public function withHasMore(bool $hasMore): self + { + $self = clone $this; + $self['hasMore'] = $hasMore; + + return $self; + } + + /** + * Metadata about the API key used for the request. Included in every response whenever a valid API key is provided, even when the response status is not 200. + * + * @param KeyMetadata|KeyMetadataShape $keyMetadata + */ + public function withKeyMetadata(KeyMetadata|array $keyMetadata): self + { + $self = clone $this; + $self['keyMetadata'] = $keyMetadata; + + return $self; + } + + /** + * Cursor for the next page. + */ + public function withNextCursor(?string $nextCursor): self + { + $self = clone $this; + $self['nextCursor'] = $nextCursor; + + return $self; + } +} diff --git a/src/Batch/BatchGetResultsResponse/Data.php b/src/Batch/BatchGetResultsResponse/Data.php new file mode 100644 index 0000000..27b46ba --- /dev/null +++ b/src/Batch/BatchGetResultsResponse/Data.php @@ -0,0 +1,38 @@ +|array + */ + public static function variants(): array + { + return ['ok' => ScrapedPage::class, 'error' => FailedPage::class]; + } +} diff --git a/src/Batch/BatchGetResultsResponse/Data/FailedPage.php b/src/Batch/BatchGetResultsResponse/Data/FailedPage.php new file mode 100644 index 0000000..ccdb3b1 --- /dev/null +++ b/src/Batch/BatchGetResultsResponse/Data/FailedPage.php @@ -0,0 +1,183 @@ +|null, + * } + */ +final class FailedPage implements BaseModel +{ + /** @use SdkModel */ + use SdkModel; + + /** + * The page could not be scraped. + * + * @var 'error' $status + */ + #[Required] + public string $status = 'error'; + + /** + * Why the page failed. + */ + #[Required('error_code')] + public string $errorCode; + + /** + * Human-readable failure detail. + */ + #[Required] + public string $message; + + /** + * URL as submitted, or as discovered by the crawl. + */ + #[Required] + public string $url; + + /** + * Caller-supplied identifier echoed from submission. + */ + #[Optional('itemId')] + public ?string $itemID; + + /** + * Caller-supplied metadata echoed from submission. + * + * @var array|null $meta + */ + #[Optional(map: 'mixed')] + public ?array $meta; + + /** + * `new FailedPage()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * FailedPage::with(errorCode: ..., message: ..., url: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new FailedPage)->withErrorCode(...)->withMessage(...)->withURL(...) + * ``` + */ + 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 array|null $meta + */ + public static function with( + string $errorCode, + string $message, + string $url, + ?string $itemID = null, + ?array $meta = null, + ): self { + $self = new self; + + $self['errorCode'] = $errorCode; + $self['message'] = $message; + $self['url'] = $url; + + null !== $itemID && $self['itemID'] = $itemID; + null !== $meta && $self['meta'] = $meta; + + return $self; + } + + /** + * Why the page failed. + */ + public function withErrorCode(string $errorCode): self + { + $self = clone $this; + $self['errorCode'] = $errorCode; + + return $self; + } + + /** + * Human-readable failure detail. + */ + public function withMessage(string $message): self + { + $self = clone $this; + $self['message'] = $message; + + return $self; + } + + /** + * The page could not be scraped. + * + * @param 'error' $status + */ + public function withStatus(string $status): self + { + $self = clone $this; + $self['status'] = $status; + + return $self; + } + + /** + * URL as submitted, or as discovered by the crawl. + */ + public function withURL(string $url): self + { + $self = clone $this; + $self['url'] = $url; + + return $self; + } + + /** + * Caller-supplied identifier echoed from submission. + */ + public function withItemID(string $itemID): self + { + $self = clone $this; + $self['itemID'] = $itemID; + + return $self; + } + + /** + * Caller-supplied metadata echoed from submission. + * + * @param array $meta + */ + public function withMeta(array $meta): self + { + $self = clone $this; + $self['meta'] = $meta; + + return $self; + } +} diff --git a/src/Batch/BatchGetResultsResponse/Data/ScrapedPage.php b/src/Batch/BatchGetResultsResponse/Data/ScrapedPage.php new file mode 100644 index 0000000..aafb7cf --- /dev/null +++ b/src/Batch/BatchGetResultsResponse/Data/ScrapedPage.php @@ -0,0 +1,253 @@ +|null, + * } + */ +final class ScrapedPage implements BaseModel +{ + /** @use SdkModel */ + use SdkModel; + + /** + * The page was scraped. + * + * @var 'ok' $status + */ + #[Required] + public string $status = 'ok'; + + /** + * URL the content was read from, after redirects. + */ + #[Required('final_url')] + public string $finalURL; + + /** + * HTTP status of the final response, when known. + */ + #[Required('http_status')] + public ?int $httpStatus; + + /** + * Metadata extracted from the scraped page HTML. + */ + #[Required] + public Metadata $metadata; + + /** + * URL as submitted, or as discovered by the crawl. + */ + #[Required] + public string $url; + + /** + * Raw page HTML. Present on html batches. + */ + #[Optional] + public ?string $html; + + /** + * Caller-supplied identifier echoed from submission. + */ + #[Optional('itemId')] + public ?string $itemID; + + /** + * Page content as Markdown. Present on markdown batches. + */ + #[Optional] + public ?string $markdown; + + /** + * Caller-supplied metadata echoed from submission. + * + * @var array|null $meta + */ + #[Optional(map: 'mixed')] + public ?array $meta; + + /** + * `new ScrapedPage()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * ScrapedPage::with(finalURL: ..., httpStatus: ..., metadata: ..., url: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new ScrapedPage) + * ->withFinalURL(...) + * ->withHTTPStatus(...) + * ->withMetadata(...) + * ->withURL(...) + * ``` + */ + 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 Metadata|MetadataShape $metadata + * @param array|null $meta + */ + public static function with( + string $finalURL, + ?int $httpStatus, + Metadata|array $metadata, + string $url, + ?string $html = null, + ?string $itemID = null, + ?string $markdown = null, + ?array $meta = null, + ): self { + $self = new self; + + $self['finalURL'] = $finalURL; + $self['httpStatus'] = $httpStatus; + $self['metadata'] = $metadata; + $self['url'] = $url; + + null !== $html && $self['html'] = $html; + null !== $itemID && $self['itemID'] = $itemID; + null !== $markdown && $self['markdown'] = $markdown; + null !== $meta && $self['meta'] = $meta; + + return $self; + } + + /** + * URL the content was read from, after redirects. + */ + public function withFinalURL(string $finalURL): self + { + $self = clone $this; + $self['finalURL'] = $finalURL; + + return $self; + } + + /** + * HTTP status of the final response, when known. + */ + public function withHTTPStatus(?int $httpStatus): self + { + $self = clone $this; + $self['httpStatus'] = $httpStatus; + + return $self; + } + + /** + * Metadata extracted from the scraped page HTML. + * + * @param Metadata|MetadataShape $metadata + */ + public function withMetadata(Metadata|array $metadata): self + { + $self = clone $this; + $self['metadata'] = $metadata; + + return $self; + } + + /** + * The page was scraped. + * + * @param 'ok' $status + */ + public function withStatus(string $status): self + { + $self = clone $this; + $self['status'] = $status; + + return $self; + } + + /** + * URL as submitted, or as discovered by the crawl. + */ + public function withURL(string $url): self + { + $self = clone $this; + $self['url'] = $url; + + return $self; + } + + /** + * Raw page HTML. Present on html batches. + */ + public function withHTML(string $html): self + { + $self = clone $this; + $self['html'] = $html; + + return $self; + } + + /** + * Caller-supplied identifier echoed from submission. + */ + public function withItemID(string $itemID): self + { + $self = clone $this; + $self['itemID'] = $itemID; + + return $self; + } + + /** + * Page content as Markdown. Present on markdown batches. + */ + public function withMarkdown(string $markdown): self + { + $self = clone $this; + $self['markdown'] = $markdown; + + return $self; + } + + /** + * Caller-supplied metadata echoed from submission. + * + * @param array $meta + */ + public function withMeta(array $meta): self + { + $self = clone $this; + $self['meta'] = $meta; + + return $self; + } +} diff --git a/src/Batch/BatchGetResultsResponse/Data/ScrapedPage/Metadata.php b/src/Batch/BatchGetResultsResponse/Data/ScrapedPage/Metadata.php new file mode 100644 index 0000000..d3619e8 --- /dev/null +++ b/src/Batch/BatchGetResultsResponse/Data/ScrapedPage/Metadata.php @@ -0,0 +1,479 @@ +|null, + * alternates?: list|null, + * author?: string|null, + * canonicalURL?: string|null, + * description?: string|null, + * favicon?: string|null, + * image?: string|null, + * jsonLd?: list>|null, + * keywords?: list|null, + * language?: string|null, + * modifiedTime?: string|null, + * openGraph?: array|null, + * publishedTime?: string|null, + * robots?: string|null, + * siteName?: string|null, + * title?: string|null, + * twitter?: array|null, + * } + */ +final class Metadata implements BaseModel +{ + /** @use SdkModel */ + use SdkModel; + + /** + * Final URL scraped after redirects or scraper fallback, when known. Falls back to sourceUrl when unavailable. + */ + #[Required('finalUrl')] + public string $finalURL; + + /** + * Original URL requested by the caller. + */ + #[Required('sourceUrl')] + public string $sourceURL; + + /** + * Additional non-social meta tags not promoted to top-level metadata fields. + * + * @var array|null $additionalMeta + */ + #[Optional(map: AdditionalMeta::class)] + public ?array $additionalMeta; + + /** + * Resolved alternate links from link rel=alternate tags. + * + * @var list|null $alternates + */ + #[Optional(list: Alternate::class)] + public ?array $alternates; + + /** + * Author metadata, when present. + */ + #[Optional] + public ?string $author; + + /** + * Resolved canonical URL, when present. + */ + #[Optional('canonicalUrl')] + public ?string $canonicalURL; + + /** + * Best description extracted from standard, Open Graph, or Twitter metadata. + */ + #[Optional] + public ?string $description; + + /** + * Resolved favicon URL, when present. + */ + #[Optional] + public ?string $favicon; + + /** + * Primary resolved preview image from Open Graph, Twitter, or image metadata. + */ + #[Optional] + public ?string $image; + + /** + * JSON-LD structured data blocks parsed from the page. + * + * @var list>|null $jsonLd + */ + #[Optional(list: new MapOf('mixed'))] + public ?array $jsonLd; + + /** + * Keywords extracted from the page's keywords meta tag. + * + * @var list|null $keywords + */ + #[Optional(list: 'string')] + public ?array $keywords; + + /** + * Language extracted from html lang or language meta tags. + */ + #[Optional] + public ?string $language; + + /** + * Modified timestamp/date from page metadata, when present. + */ + #[Optional] + public ?string $modifiedTime; + + /** + * Open Graph metadata with the og: prefix removed and keys camel-cased. + * + * @var array|null $openGraph + */ + #[Optional(map: OpenGraph::class)] + public ?array $openGraph; + + /** + * Published timestamp/date from page metadata, when present. + */ + #[Optional] + public ?string $publishedTime; + + /** + * Robots meta directive, when present. + */ + #[Optional] + public ?string $robots; + + /** + * Site or application name from page metadata. + */ + #[Optional] + public ?string $siteName; + + /** + * Best title extracted from the page. + */ + #[Optional] + public ?string $title; + + /** + * Twitter card metadata with the twitter: prefix removed and keys camel-cased. + * + * @var array|null $twitter + */ + #[Optional(map: Twitter::class)] + public ?array $twitter; + + /** + * `new Metadata()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * Metadata::with(finalURL: ..., sourceURL: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new Metadata)->withFinalURL(...)->withSourceURL(...) + * ``` + */ + 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 array|null $additionalMeta + * @param list|null $alternates + * @param list>|null $jsonLd + * @param list|null $keywords + * @param array|null $openGraph + * @param array|null $twitter + */ + public static function with( + string $finalURL, + string $sourceURL, + ?array $additionalMeta = null, + ?array $alternates = null, + ?string $author = null, + ?string $canonicalURL = null, + ?string $description = null, + ?string $favicon = null, + ?string $image = null, + ?array $jsonLd = null, + ?array $keywords = null, + ?string $language = null, + ?string $modifiedTime = null, + ?array $openGraph = null, + ?string $publishedTime = null, + ?string $robots = null, + ?string $siteName = null, + ?string $title = null, + ?array $twitter = null, + ): self { + $self = new self; + + $self['finalURL'] = $finalURL; + $self['sourceURL'] = $sourceURL; + + null !== $additionalMeta && $self['additionalMeta'] = $additionalMeta; + null !== $alternates && $self['alternates'] = $alternates; + null !== $author && $self['author'] = $author; + null !== $canonicalURL && $self['canonicalURL'] = $canonicalURL; + null !== $description && $self['description'] = $description; + null !== $favicon && $self['favicon'] = $favicon; + null !== $image && $self['image'] = $image; + null !== $jsonLd && $self['jsonLd'] = $jsonLd; + null !== $keywords && $self['keywords'] = $keywords; + null !== $language && $self['language'] = $language; + null !== $modifiedTime && $self['modifiedTime'] = $modifiedTime; + null !== $openGraph && $self['openGraph'] = $openGraph; + null !== $publishedTime && $self['publishedTime'] = $publishedTime; + null !== $robots && $self['robots'] = $robots; + null !== $siteName && $self['siteName'] = $siteName; + null !== $title && $self['title'] = $title; + null !== $twitter && $self['twitter'] = $twitter; + + return $self; + } + + /** + * Final URL scraped after redirects or scraper fallback, when known. Falls back to sourceUrl when unavailable. + */ + public function withFinalURL(string $finalURL): self + { + $self = clone $this; + $self['finalURL'] = $finalURL; + + return $self; + } + + /** + * Original URL requested by the caller. + */ + public function withSourceURL(string $sourceURL): self + { + $self = clone $this; + $self['sourceURL'] = $sourceURL; + + return $self; + } + + /** + * Additional non-social meta tags not promoted to top-level metadata fields. + * + * @param array $additionalMeta + */ + public function withAdditionalMeta(array $additionalMeta): self + { + $self = clone $this; + $self['additionalMeta'] = $additionalMeta; + + return $self; + } + + /** + * Resolved alternate links from link rel=alternate tags. + * + * @param list $alternates + */ + public function withAlternates(array $alternates): self + { + $self = clone $this; + $self['alternates'] = $alternates; + + return $self; + } + + /** + * Author metadata, when present. + */ + public function withAuthor(string $author): self + { + $self = clone $this; + $self['author'] = $author; + + return $self; + } + + /** + * Resolved canonical URL, when present. + */ + public function withCanonicalURL(string $canonicalURL): self + { + $self = clone $this; + $self['canonicalURL'] = $canonicalURL; + + return $self; + } + + /** + * Best description extracted from standard, Open Graph, or Twitter metadata. + */ + public function withDescription(string $description): self + { + $self = clone $this; + $self['description'] = $description; + + return $self; + } + + /** + * Resolved favicon URL, when present. + */ + public function withFavicon(string $favicon): self + { + $self = clone $this; + $self['favicon'] = $favicon; + + return $self; + } + + /** + * Primary resolved preview image from Open Graph, Twitter, or image metadata. + */ + public function withImage(string $image): self + { + $self = clone $this; + $self['image'] = $image; + + return $self; + } + + /** + * JSON-LD structured data blocks parsed from the page. + * + * @param list> $jsonLd + */ + public function withJsonLd(array $jsonLd): self + { + $self = clone $this; + $self['jsonLd'] = $jsonLd; + + return $self; + } + + /** + * Keywords extracted from the page's keywords meta tag. + * + * @param list $keywords + */ + public function withKeywords(array $keywords): self + { + $self = clone $this; + $self['keywords'] = $keywords; + + return $self; + } + + /** + * Language extracted from html lang or language meta tags. + */ + public function withLanguage(string $language): self + { + $self = clone $this; + $self['language'] = $language; + + return $self; + } + + /** + * Modified timestamp/date from page metadata, when present. + */ + public function withModifiedTime(string $modifiedTime): self + { + $self = clone $this; + $self['modifiedTime'] = $modifiedTime; + + return $self; + } + + /** + * Open Graph metadata with the og: prefix removed and keys camel-cased. + * + * @param array $openGraph + */ + public function withOpenGraph(array $openGraph): self + { + $self = clone $this; + $self['openGraph'] = $openGraph; + + return $self; + } + + /** + * Published timestamp/date from page metadata, when present. + */ + public function withPublishedTime(string $publishedTime): self + { + $self = clone $this; + $self['publishedTime'] = $publishedTime; + + return $self; + } + + /** + * Robots meta directive, when present. + */ + public function withRobots(string $robots): self + { + $self = clone $this; + $self['robots'] = $robots; + + return $self; + } + + /** + * Site or application name from page metadata. + */ + public function withSiteName(string $siteName): self + { + $self = clone $this; + $self['siteName'] = $siteName; + + return $self; + } + + /** + * Best title extracted from the page. + */ + public function withTitle(string $title): self + { + $self = clone $this; + $self['title'] = $title; + + return $self; + } + + /** + * Twitter card metadata with the twitter: prefix removed and keys camel-cased. + * + * @param array $twitter + */ + public function withTwitter(array $twitter): self + { + $self = clone $this; + $self['twitter'] = $twitter; + + return $self; + } +} diff --git a/src/Batch/BatchGetResultsResponse/Data/ScrapedPage/Metadata/AdditionalMeta.php b/src/Batch/BatchGetResultsResponse/Data/ScrapedPage/Metadata/AdditionalMeta.php new file mode 100644 index 0000000..39c3800 --- /dev/null +++ b/src/Batch/BatchGetResultsResponse/Data/ScrapedPage/Metadata/AdditionalMeta.php @@ -0,0 +1,27 @@ + + * @phpstan-type AdditionalMetaShape = AdditionalMetaVariants + */ +final class AdditionalMeta implements ConverterSource +{ + use SdkUnion; + + /** + * @return list|array + */ + public static function variants(): array + { + return ['string', new ListOf('string')]; + } +} diff --git a/src/Batch/BatchGetResultsResponse/Data/ScrapedPage/Metadata/Alternate.php b/src/Batch/BatchGetResultsResponse/Data/ScrapedPage/Metadata/Alternate.php new file mode 100644 index 0000000..43ab743 --- /dev/null +++ b/src/Batch/BatchGetResultsResponse/Data/ScrapedPage/Metadata/Alternate.php @@ -0,0 +1,130 @@ + */ + use SdkModel; + + /** + * Resolved alternate URL. + */ + #[Required] + public string $href; + + /** + * Language or locale for the alternate URL, when present. + */ + #[Optional] + public ?string $hreflang; + + /** + * Alternate resource title, when present. + */ + #[Optional] + public ?string $title; + + /** + * Alternate resource MIME type, when present. + */ + #[Optional] + public ?string $type; + + /** + * `new Alternate()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * Alternate::with(href: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new Alternate)->withHref(...) + * ``` + */ + 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 $href, + ?string $hreflang = null, + ?string $title = null, + ?string $type = null, + ): self { + $self = new self; + + $self['href'] = $href; + + null !== $hreflang && $self['hreflang'] = $hreflang; + null !== $title && $self['title'] = $title; + null !== $type && $self['type'] = $type; + + return $self; + } + + /** + * Resolved alternate URL. + */ + public function withHref(string $href): self + { + $self = clone $this; + $self['href'] = $href; + + return $self; + } + + /** + * Language or locale for the alternate URL, when present. + */ + public function withHreflang(string $hreflang): self + { + $self = clone $this; + $self['hreflang'] = $hreflang; + + return $self; + } + + /** + * Alternate resource title, when present. + */ + public function withTitle(string $title): self + { + $self = clone $this; + $self['title'] = $title; + + return $self; + } + + /** + * Alternate resource MIME type, when present. + */ + public function withType(string $type): self + { + $self = clone $this; + $self['type'] = $type; + + return $self; + } +} diff --git a/src/Batch/BatchGetResultsResponse/Data/ScrapedPage/Metadata/OpenGraph.php b/src/Batch/BatchGetResultsResponse/Data/ScrapedPage/Metadata/OpenGraph.php new file mode 100644 index 0000000..4b6b571 --- /dev/null +++ b/src/Batch/BatchGetResultsResponse/Data/ScrapedPage/Metadata/OpenGraph.php @@ -0,0 +1,27 @@ + + * @phpstan-type OpenGraphShape = OpenGraphVariants + */ +final class OpenGraph implements ConverterSource +{ + use SdkUnion; + + /** + * @return list|array + */ + public static function variants(): array + { + return ['string', new ListOf('string')]; + } +} diff --git a/src/Batch/BatchGetResultsResponse/Data/ScrapedPage/Metadata/Twitter.php b/src/Batch/BatchGetResultsResponse/Data/ScrapedPage/Metadata/Twitter.php new file mode 100644 index 0000000..e9861f6 --- /dev/null +++ b/src/Batch/BatchGetResultsResponse/Data/ScrapedPage/Metadata/Twitter.php @@ -0,0 +1,27 @@ + + * @phpstan-type TwitterShape = TwitterVariants + */ +final class Twitter implements ConverterSource +{ + use SdkUnion; + + /** + * @return list|array + */ + public static function variants(): array + { + return ['string', new ListOf('string')]; + } +} diff --git a/src/Batch/BatchGetResultsResponse/KeyMetadata.php b/src/Batch/BatchGetResultsResponse/KeyMetadata.php new file mode 100644 index 0000000..4ccf532 --- /dev/null +++ b/src/Batch/BatchGetResultsResponse/KeyMetadata.php @@ -0,0 +1,92 @@ + */ + use SdkModel; + + /** + * The number of credits consumed by this request. + */ + #[Required('credits_consumed')] + public int $creditsConsumed; + + /** + * The number of credits remaining for your organization after this request. + */ + #[Required('credits_remaining')] + public int $creditsRemaining; + + /** + * `new KeyMetadata()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * KeyMetadata::with(creditsConsumed: ..., creditsRemaining: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new KeyMetadata)->withCreditsConsumed(...)->withCreditsRemaining(...) + * ``` + */ + 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 $creditsConsumed, + int $creditsRemaining + ): self { + $self = new self; + + $self['creditsConsumed'] = $creditsConsumed; + $self['creditsRemaining'] = $creditsRemaining; + + return $self; + } + + /** + * The number of credits consumed by this request. + */ + public function withCreditsConsumed(int $creditsConsumed): self + { + $self = clone $this; + $self['creditsConsumed'] = $creditsConsumed; + + return $self; + } + + /** + * The number of credits remaining for your organization after this request. + */ + public function withCreditsRemaining(int $creditsRemaining): self + { + $self = clone $this; + $self['creditsRemaining'] = $creditsRemaining; + + return $self; + } +} diff --git a/src/Batch/BatchListParams.php b/src/Batch/BatchListParams.php new file mode 100644 index 0000000..1cb99f1 --- /dev/null +++ b/src/Batch/BatchListParams.php @@ -0,0 +1,176 @@ +, + * status?: null|Status|value-of, + * tags?: string|null, + * } + */ +final class BatchListParams implements BaseModel +{ + /** @use SdkModel */ + use SdkModel; + use SdkParams; + + /** + * Cursor from the previous page. + */ + #[Optional] + public ?string $cursor; + + /** + * Batches per page. Defaults to 25. + */ + #[Optional] + public ?int $limit; + + /** + * Free-text search term, matched against the batch id, crawl source (start URL or sitemap domain), and tags. + */ + #[Optional] + public ?string $q; + + /** + * `prefix` for as-you-type prefix matching (default), `exact` for full-token matching. + * + * @var value-of|null $searchType + */ + #[Optional(enum: SearchType::class)] + public ?string $searchType; + + /** + * Filter by status. + * + * @var value-of|null $status + */ + #[Optional(enum: Status::class)] + public ?string $status; + + /** + * Comma-separated list of tags to filter by (matches batches having any of them). + */ + #[Optional] + public ?string $tags; + + 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 SearchType|value-of|null $searchType + * @param Status|value-of|null $status + */ + public static function with( + ?string $cursor = null, + ?int $limit = null, + ?string $q = null, + SearchType|string|null $searchType = null, + Status|string|null $status = null, + ?string $tags = null, + ): self { + $self = new self; + + null !== $cursor && $self['cursor'] = $cursor; + null !== $limit && $self['limit'] = $limit; + null !== $q && $self['q'] = $q; + null !== $searchType && $self['searchType'] = $searchType; + null !== $status && $self['status'] = $status; + null !== $tags && $self['tags'] = $tags; + + return $self; + } + + /** + * Cursor from the previous page. + */ + public function withCursor(string $cursor): self + { + $self = clone $this; + $self['cursor'] = $cursor; + + return $self; + } + + /** + * Batches per page. Defaults to 25. + */ + public function withLimit(int $limit): self + { + $self = clone $this; + $self['limit'] = $limit; + + return $self; + } + + /** + * Free-text search term, matched against the batch id, crawl source (start URL or sitemap domain), and tags. + */ + public function withQ(string $q): self + { + $self = clone $this; + $self['q'] = $q; + + return $self; + } + + /** + * `prefix` for as-you-type prefix matching (default), `exact` for full-token matching. + * + * @param SearchType|value-of $searchType + */ + public function withSearchType(SearchType|string $searchType): self + { + $self = clone $this; + $self['searchType'] = $searchType; + + return $self; + } + + /** + * Filter by status. + * + * @param Status|value-of $status + */ + public function withStatus(Status|string $status): self + { + $self = clone $this; + $self['status'] = $status; + + return $self; + } + + /** + * Comma-separated list of tags to filter by (matches batches having any of them). + */ + public function withTags(string $tags): self + { + $self = clone $this; + $self['tags'] = $tags; + + return $self; + } +} diff --git a/src/Batch/BatchListParams/SearchType.php b/src/Batch/BatchListParams/SearchType.php new file mode 100644 index 0000000..3bf299a --- /dev/null +++ b/src/Batch/BatchListParams/SearchType.php @@ -0,0 +1,15 @@ +|null, + * hasMore?: bool|null, + * keyMetadata?: null|KeyMetadata|KeyMetadataShape, + * nextCursor?: string|null, + * } + */ +final class BatchListResponse implements BaseModel +{ + /** @use SdkModel */ + use SdkModel; + + /** + * Batches on this page. + * + * @var list|null $data + */ + #[Optional(list: Data::class)] + public ?array $data; + + /** + * Whether another page is available. + */ + #[Optional('has_more')] + public ?bool $hasMore; + + /** + * Metadata about the API key used for the request. Included in every response whenever a valid API key is provided, even when the response status is not 200. + */ + #[Optional('key_metadata')] + public ?KeyMetadata $keyMetadata; + + /** + * Cursor for the next page. + */ + #[Optional('next_cursor', nullable: true)] + public ?string $nextCursor; + + 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|null $data + * @param KeyMetadata|KeyMetadataShape|null $keyMetadata + */ + public static function with( + ?array $data = null, + ?bool $hasMore = null, + KeyMetadata|array|null $keyMetadata = null, + ?string $nextCursor = null, + ): self { + $self = new self; + + null !== $data && $self['data'] = $data; + null !== $hasMore && $self['hasMore'] = $hasMore; + null !== $keyMetadata && $self['keyMetadata'] = $keyMetadata; + null !== $nextCursor && $self['nextCursor'] = $nextCursor; + + return $self; + } + + /** + * Batches on this page. + * + * @param list $data + */ + public function withData(array $data): self + { + $self = clone $this; + $self['data'] = $data; + + return $self; + } + + /** + * Whether another page is available. + */ + public function withHasMore(bool $hasMore): self + { + $self = clone $this; + $self['hasMore'] = $hasMore; + + return $self; + } + + /** + * Metadata about the API key used for the request. Included in every response whenever a valid API key is provided, even when the response status is not 200. + * + * @param KeyMetadata|KeyMetadataShape $keyMetadata + */ + public function withKeyMetadata(KeyMetadata|array $keyMetadata): self + { + $self = clone $this; + $self['keyMetadata'] = $keyMetadata; + + return $self; + } + + /** + * Cursor for the next page. + */ + public function withNextCursor(?string $nextCursor): self + { + $self = clone $this; + $self['nextCursor'] = $nextCursor; + + return $self; + } +} diff --git a/src/Batch/BatchListResponse/Data.php b/src/Batch/BatchListResponse/Data.php new file mode 100644 index 0000000..71940da --- /dev/null +++ b/src/Batch/BatchListResponse/Data.php @@ -0,0 +1,375 @@ +, + * input: Input|InputShape, + * mode: Mode|value-of, + * progress: Progress|ProgressShape, + * results: null|Results|ResultsShape, + * status: Status|value-of, + * tags: list, + * timing: Timing|TimingShape, + * type: Type|value-of, + * } + */ +final class Data implements BaseModel +{ + /** @use SdkModel */ + use SdkModel; + + /** + * Batch ID used to retrieve or cancel the job. + */ + #[Required] + public string $id; + + /** + * Reserved and used credits. + */ + #[Required] + public Credits $credits; + + /** + * Why the batch failed. + */ + #[Required] + public ?Error $error; + + /** + * Page failures grouped by error code. + * + * @var list $errors + */ + #[Required(list: ErrorCount::class)] + public array $errors; + + /** + * Submission counts. + */ + #[Required] + public Input $input; + + /** + * How pages are selected. + * + * @var value-of $mode + */ + #[Required(enum: Mode::class)] + public string $mode; + + /** + * Current processing counts. Use `status` to check completion. + */ + #[Required] + public Progress $progress; + + /** + * Download links available when the batch finishes. GET /batch/{batch_id}/results serves the same records as paginated JSON. + */ + #[Required] + public ?Results $results; + + /** + * Current state. `completed`, `cancelled`, and `failed` are final. + * + * @var value-of $status + */ + #[Required(enum: Status::class)] + public string $status; + + /** + * Tags stored on the batch at submission. + * + * @var list $tags + */ + #[Required(list: 'string')] + public array $tags; + + #[Required] + public Timing $timing; + + /** + * Output format. + * + * @var value-of $type + */ + #[Required(enum: Type::class)] + public string $type; + + /** + * `new Data()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * Data::with( + * id: ..., + * credits: ..., + * error: ..., + * errors: ..., + * input: ..., + * mode: ..., + * progress: ..., + * results: ..., + * status: ..., + * tags: ..., + * timing: ..., + * type: ..., + * ) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new Data) + * ->withID(...) + * ->withCredits(...) + * ->withError(...) + * ->withErrors(...) + * ->withInput(...) + * ->withMode(...) + * ->withProgress(...) + * ->withResults(...) + * ->withStatus(...) + * ->withTags(...) + * ->withTiming(...) + * ->withType(...) + * ``` + */ + 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 Credits|CreditsShape $credits + * @param Error|ErrorShape|null $error + * @param list $errors + * @param Input|InputShape $input + * @param Mode|value-of $mode + * @param Progress|ProgressShape $progress + * @param Results|ResultsShape|null $results + * @param Status|value-of $status + * @param list $tags + * @param Timing|TimingShape $timing + * @param Type|value-of $type + */ + public static function with( + string $id, + Credits|array $credits, + Error|array|null $error, + array $errors, + Input|array $input, + Mode|string $mode, + Progress|array $progress, + Results|array|null $results, + Status|string $status, + array $tags, + Timing|array $timing, + Type|string $type, + ): self { + $self = new self; + + $self['id'] = $id; + $self['credits'] = $credits; + $self['error'] = $error; + $self['errors'] = $errors; + $self['input'] = $input; + $self['mode'] = $mode; + $self['progress'] = $progress; + $self['results'] = $results; + $self['status'] = $status; + $self['tags'] = $tags; + $self['timing'] = $timing; + $self['type'] = $type; + + return $self; + } + + /** + * Batch ID used to retrieve or cancel the job. + */ + public function withID(string $id): self + { + $self = clone $this; + $self['id'] = $id; + + return $self; + } + + /** + * Reserved and used credits. + * + * @param Credits|CreditsShape $credits + */ + public function withCredits(Credits|array $credits): self + { + $self = clone $this; + $self['credits'] = $credits; + + return $self; + } + + /** + * Why the batch failed. + * + * @param Error|ErrorShape|null $error + */ + public function withError(Error|array|null $error): self + { + $self = clone $this; + $self['error'] = $error; + + return $self; + } + + /** + * Page failures grouped by error code. + * + * @param list $errors + */ + public function withErrors(array $errors): self + { + $self = clone $this; + $self['errors'] = $errors; + + return $self; + } + + /** + * Submission counts. + * + * @param Input|InputShape $input + */ + public function withInput(Input|array $input): self + { + $self = clone $this; + $self['input'] = $input; + + return $self; + } + + /** + * How pages are selected. + * + * @param Mode|value-of $mode + */ + public function withMode(Mode|string $mode): self + { + $self = clone $this; + $self['mode'] = $mode; + + return $self; + } + + /** + * Current processing counts. Use `status` to check completion. + * + * @param Progress|ProgressShape $progress + */ + public function withProgress(Progress|array $progress): self + { + $self = clone $this; + $self['progress'] = $progress; + + return $self; + } + + /** + * Download links available when the batch finishes. GET /batch/{batch_id}/results serves the same records as paginated JSON. + * + * @param Results|ResultsShape|null $results + */ + public function withResults(Results|array|null $results): self + { + $self = clone $this; + $self['results'] = $results; + + return $self; + } + + /** + * Current state. `completed`, `cancelled`, and `failed` are final. + * + * @param Status|value-of $status + */ + public function withStatus(Status|string $status): self + { + $self = clone $this; + $self['status'] = $status; + + return $self; + } + + /** + * Tags stored on the batch at submission. + * + * @param list $tags + */ + public function withTags(array $tags): self + { + $self = clone $this; + $self['tags'] = $tags; + + return $self; + } + + /** + * @param Timing|TimingShape $timing + */ + public function withTiming(Timing|array $timing): self + { + $self = clone $this; + $self['timing'] = $timing; + + return $self; + } + + /** + * Output format. + * + * @param Type|value-of $type + */ + public function withType(Type|string $type): self + { + $self = clone $this; + $self['type'] = $type; + + return $self; + } +} diff --git a/src/Batch/BatchListResponse/Data/Credits.php b/src/Batch/BatchListResponse/Data/Credits.php new file mode 100644 index 0000000..285e604 --- /dev/null +++ b/src/Batch/BatchListResponse/Data/Credits.php @@ -0,0 +1,88 @@ + */ + use SdkModel; + + /** + * Credits used by successful pages. + */ + #[Required] + public int $charged; + + /** + * Credits reserved when the batch was accepted. + */ + #[Required] + public int $estimated; + + /** + * `new Credits()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * Credits::with(charged: ..., estimated: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new Credits)->withCharged(...)->withEstimated(...) + * ``` + */ + 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 $charged, int $estimated): self + { + $self = new self; + + $self['charged'] = $charged; + $self['estimated'] = $estimated; + + return $self; + } + + /** + * Credits used by successful pages. + */ + public function withCharged(int $charged): self + { + $self = clone $this; + $self['charged'] = $charged; + + return $self; + } + + /** + * Credits reserved when the batch was accepted. + */ + public function withEstimated(int $estimated): self + { + $self = clone $this; + $self['estimated'] = $estimated; + + return $self; + } +} diff --git a/src/Batch/BatchListResponse/Data/Input.php b/src/Batch/BatchListResponse/Data/Input.php new file mode 100644 index 0000000..f9423b6 --- /dev/null +++ b/src/Batch/BatchListResponse/Data/Input.php @@ -0,0 +1,134 @@ + */ + use SdkModel; + + /** + * Pages accepted, or the crawl page limit. Credits are reserved for this count. + */ + #[Required] + public int $accepted; + + /** + * Duplicate URL and `itemId` pairs skipped. Always 0 for crawls. + */ + #[Required] + public int $duplicates; + + /** + * Pages rejected during validation. + */ + #[Required] + public int $invalid; + + /** + * Pages submitted before validation. For a crawl, the page limit. + */ + #[Required] + public int $submitted; + + /** + * `new Input()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * Input::with(accepted: ..., duplicates: ..., invalid: ..., submitted: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new Input) + * ->withAccepted(...) + * ->withDuplicates(...) + * ->withInvalid(...) + * ->withSubmitted(...) + * ``` + */ + 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 $accepted, + int $duplicates, + int $invalid, + int $submitted + ): self { + $self = new self; + + $self['accepted'] = $accepted; + $self['duplicates'] = $duplicates; + $self['invalid'] = $invalid; + $self['submitted'] = $submitted; + + return $self; + } + + /** + * Pages accepted, or the crawl page limit. Credits are reserved for this count. + */ + public function withAccepted(int $accepted): self + { + $self = clone $this; + $self['accepted'] = $accepted; + + return $self; + } + + /** + * Duplicate URL and `itemId` pairs skipped. Always 0 for crawls. + */ + public function withDuplicates(int $duplicates): self + { + $self = clone $this; + $self['duplicates'] = $duplicates; + + return $self; + } + + /** + * Pages rejected during validation. + */ + public function withInvalid(int $invalid): self + { + $self = clone $this; + $self['invalid'] = $invalid; + + return $self; + } + + /** + * Pages submitted before validation. For a crawl, the page limit. + */ + public function withSubmitted(int $submitted): self + { + $self = clone $this; + $self['submitted'] = $submitted; + + return $self; + } +} diff --git a/src/Batch/BatchListResponse/Data/Mode.php b/src/Batch/BatchListResponse/Data/Mode.php new file mode 100644 index 0000000..d8a11a7 --- /dev/null +++ b/src/Batch/BatchListResponse/Data/Mode.php @@ -0,0 +1,15 @@ + */ + use SdkModel; + + /** + * Pages that could not be scraped. + */ + #[Required] + public int $failed; + + /** + * Accepted pages not yet attempted. Always 0 once the batch completes; a crawl can finish under its page limit when the site has no more reachable pages. + */ + #[Required] + public int $pending; + + /** + * Pages scraped successfully. + */ + #[Required] + public int $succeeded; + + /** + * `new Progress()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * Progress::with(failed: ..., pending: ..., succeeded: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new Progress)->withFailed(...)->withPending(...)->withSucceeded(...) + * ``` + */ + 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 $failed, int $pending, int $succeeded): self + { + $self = new self; + + $self['failed'] = $failed; + $self['pending'] = $pending; + $self['succeeded'] = $succeeded; + + return $self; + } + + /** + * Pages that could not be scraped. + */ + public function withFailed(int $failed): self + { + $self = clone $this; + $self['failed'] = $failed; + + return $self; + } + + /** + * Accepted pages not yet attempted. Always 0 once the batch completes; a crawl can finish under its page limit when the site has no more reachable pages. + */ + public function withPending(int $pending): self + { + $self = clone $this; + $self['pending'] = $pending; + + return $self; + } + + /** + * Pages scraped successfully. + */ + public function withSucceeded(int $succeeded): self + { + $self = clone $this; + $self['succeeded'] = $succeeded; + + return $self; + } +} diff --git a/src/Batch/BatchListResponse/Data/Results.php b/src/Batch/BatchListResponse/Data/Results.php new file mode 100644 index 0000000..8ebad63 --- /dev/null +++ b/src/Batch/BatchListResponse/Data/Results.php @@ -0,0 +1,99 @@ + + * } + */ +final class Results implements BaseModel +{ + /** @use SdkModel */ + use SdkModel; + + /** + * When the download URLs expire. + */ + #[Required('expires_at')] + public string $expiresAt; + + /** + * Result files. Order is not guaranteed. + * + * @var list $files + */ + #[Required(list: File::class)] + public array $files; + + /** + * `new Results()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * Results::with(expiresAt: ..., files: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new Results)->withExpiresAt(...)->withFiles(...) + * ``` + */ + 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 $files + */ + public static function with(string $expiresAt, array $files): self + { + $self = new self; + + $self['expiresAt'] = $expiresAt; + $self['files'] = $files; + + return $self; + } + + /** + * When the download URLs expire. + */ + public function withExpiresAt(string $expiresAt): self + { + $self = clone $this; + $self['expiresAt'] = $expiresAt; + + return $self; + } + + /** + * Result files. Order is not guaranteed. + * + * @param list $files + */ + public function withFiles(array $files): self + { + $self = clone $this; + $self['files'] = $files; + + return $self; + } +} diff --git a/src/Batch/BatchListResponse/Data/Results/File.php b/src/Batch/BatchListResponse/Data/Results/File.php new file mode 100644 index 0000000..9e8b538 --- /dev/null +++ b/src/Batch/BatchListResponse/Data/Results/File.php @@ -0,0 +1,104 @@ + */ + use SdkModel; + + /** + * Compressed file size in bytes. + */ + #[Required] + public int $bytes; + + /** + * Results in this file. + */ + #[Required] + public int $items; + + /** + * Temporary URL for a gzipped NDJSON file. + */ + #[Required] + public string $url; + + /** + * `new File()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * File::with(bytes: ..., items: ..., url: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new File)->withBytes(...)->withItems(...)->withURL(...) + * ``` + */ + 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 $bytes, int $items, string $url): self + { + $self = new self; + + $self['bytes'] = $bytes; + $self['items'] = $items; + $self['url'] = $url; + + return $self; + } + + /** + * Compressed file size in bytes. + */ + public function withBytes(int $bytes): self + { + $self = clone $this; + $self['bytes'] = $bytes; + + return $self; + } + + /** + * Results in this file. + */ + public function withItems(int $items): self + { + $self = clone $this; + $self['items'] = $items; + + return $self; + } + + /** + * Temporary URL for a gzipped NDJSON file. + */ + public function withURL(string $url): self + { + $self = clone $this; + $self['url'] = $url; + + return $self; + } +} diff --git a/src/Batch/BatchListResponse/Data/Status.php b/src/Batch/BatchListResponse/Data/Status.php new file mode 100644 index 0000000..b937aad --- /dev/null +++ b/src/Batch/BatchListResponse/Data/Status.php @@ -0,0 +1,23 @@ + */ + use SdkModel; + + /** + * When processing finished. Null while active. + */ + #[Required('completed_at')] + public ?string $completedAt; + + /** + * When the batch was created. + */ + #[Required('created_at')] + public string $createdAt; + + /** + * When processing started. Null while queued. + */ + #[Required('started_at')] + public ?string $startedAt; + + /** + * `new Timing()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * Timing::with(completedAt: ..., createdAt: ..., startedAt: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new Timing)->withCompletedAt(...)->withCreatedAt(...)->withStartedAt(...) + * ``` + */ + 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 $completedAt, + string $createdAt, + ?string $startedAt + ): self { + $self = new self; + + $self['completedAt'] = $completedAt; + $self['createdAt'] = $createdAt; + $self['startedAt'] = $startedAt; + + return $self; + } + + /** + * When processing finished. Null while active. + */ + public function withCompletedAt(?string $completedAt): self + { + $self = clone $this; + $self['completedAt'] = $completedAt; + + return $self; + } + + /** + * When the batch was created. + */ + public function withCreatedAt(string $createdAt): self + { + $self = clone $this; + $self['createdAt'] = $createdAt; + + return $self; + } + + /** + * When processing started. Null while queued. + */ + public function withStartedAt(?string $startedAt): self + { + $self = clone $this; + $self['startedAt'] = $startedAt; + + return $self; + } +} diff --git a/src/Batch/BatchListResponse/Data/Type.php b/src/Batch/BatchListResponse/Data/Type.php new file mode 100644 index 0000000..b93f331 --- /dev/null +++ b/src/Batch/BatchListResponse/Data/Type.php @@ -0,0 +1,15 @@ + */ + use SdkModel; + + /** + * The number of credits consumed by this request. + */ + #[Required('credits_consumed')] + public int $creditsConsumed; + + /** + * The number of credits remaining for your organization after this request. + */ + #[Required('credits_remaining')] + public int $creditsRemaining; + + /** + * `new KeyMetadata()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * KeyMetadata::with(creditsConsumed: ..., creditsRemaining: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new KeyMetadata)->withCreditsConsumed(...)->withCreditsRemaining(...) + * ``` + */ + 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 $creditsConsumed, + int $creditsRemaining + ): self { + $self = new self; + + $self['creditsConsumed'] = $creditsConsumed; + $self['creditsRemaining'] = $creditsRemaining; + + return $self; + } + + /** + * The number of credits consumed by this request. + */ + public function withCreditsConsumed(int $creditsConsumed): self + { + $self = clone $this; + $self['creditsConsumed'] = $creditsConsumed; + + return $self; + } + + /** + * The number of credits remaining for your organization after this request. + */ + public function withCreditsRemaining(int $creditsRemaining): self + { + $self = clone $this; + $self['creditsRemaining'] = $creditsRemaining; + + return $self; + } +} diff --git a/src/Batch/BatchSubmitParams.php b/src/Batch/BatchSubmitParams.php new file mode 100644 index 0000000..c1a94b3 --- /dev/null +++ b/src/Batch/BatchSubmitParams.php @@ -0,0 +1,131 @@ +|null, + * timeoutMs?: int|null, + * } + */ +final class BatchSubmitParams implements BaseModel +{ + /** @use SdkModel */ + use SdkModel; + use SdkParams; + + /** + * Known identifiers for the person. At least one identifier is required. + */ + #[Required] + public Identifiers $identifiers; + + /** + * 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). + */ + #[Optional('timeoutMS')] + public ?int $timeoutMs; + + /** + * `new BatchSubmitParams()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * BatchSubmitParams::with(identifiers: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new BatchSubmitParams)->withIdentifiers(...) + * ``` + */ + 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 Identifiers|IdentifiersShape $identifiers + * @param list|null $tags + */ + public static function with( + Identifiers|array $identifiers, + ?array $tags = null, + ?int $timeoutMs = null + ): self { + $self = new self; + + $self['identifiers'] = $identifiers; + + null !== $tags && $self['tags'] = $tags; + null !== $timeoutMs && $self['timeoutMs'] = $timeoutMs; + + return $self; + } + + /** + * Known identifiers for the person. At least one identifier is required. + * + * @param Identifiers|IdentifiersShape $identifiers + */ + public function withIdentifiers(Identifiers|array $identifiers): self + { + $self = clone $this; + $self['identifiers'] = $identifiers; + + 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). + */ + public function withTimeoutMs(int $timeoutMs): self + { + $self = clone $this; + $self['timeoutMs'] = $timeoutMs; + + return $self; + } +} diff --git a/src/Batch/BatchSubmitParams/Identifiers.php b/src/Batch/BatchSubmitParams/Identifiers.php new file mode 100644 index 0000000..5ceb6cb --- /dev/null +++ b/src/Batch/BatchSubmitParams/Identifiers.php @@ -0,0 +1,56 @@ + */ + use SdkModel; + + /** + * LinkedIn profile URL, e.g. https://www.linkedin.com/in/yahia-bakour/. + */ + #[Optional('linkedinUrl')] + public ?string $linkedinURL; + + 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 $linkedinURL = null): self + { + $self = new self; + + null !== $linkedinURL && $self['linkedinURL'] = $linkedinURL; + + return $self; + } + + /** + * LinkedIn profile URL, e.g. https://www.linkedin.com/in/yahia-bakour/. + */ + public function withLinkedinURL(string $linkedinURL): self + { + $self = clone $this; + $self['linkedinURL'] = $linkedinURL; + + return $self; + } +} diff --git a/src/Batch/BatchSubmitResponse.php b/src/Batch/BatchSubmitResponse.php new file mode 100644 index 0000000..dd7d5a6 --- /dev/null +++ b/src/Batch/BatchSubmitResponse.php @@ -0,0 +1,186 @@ +, + * metadata: Metadata|MetadataShape, + * person: Person|PersonShape, + * status: Status|value-of, + * keyMetadata?: null|KeyMetadata|KeyMetadataShape, + * } + */ +final class BatchSubmitResponse implements BaseModel +{ + /** @use SdkModel */ + use SdkModel; + + /** + * HTTP status code. + * + * @var value-of $code + */ + #[Required(enum: Code::class)] + public int $code; + + /** + * Additional response details. + */ + #[Required] + public Metadata $metadata; + + /** + * Retrieved person profile. + */ + #[Required] + public Person $person; + + /** + * Response status. + * + * @var value-of $status + */ + #[Required(enum: Status::class)] + public string $status; + + /** + * Metadata about the API key used for the request. Included in every response whenever a valid API key is provided, even when the response status is not 200. + */ + #[Optional('key_metadata')] + public ?KeyMetadata $keyMetadata; + + /** + * `new BatchSubmitResponse()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * BatchSubmitResponse::with(code: ..., metadata: ..., person: ..., status: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new BatchSubmitResponse) + * ->withCode(...) + * ->withMetadata(...) + * ->withPerson(...) + * ->withStatus(...) + * ``` + */ + public function __construct() + { + $this->initialize(); + } + + /** + * Construct an instance from the required parameters. + * + * You must use named parameters to construct any parameters with a default value. + * + * @param Code|value-of $code + * @param Metadata|MetadataShape $metadata + * @param Person|PersonShape $person + * @param Status|value-of $status + * @param KeyMetadata|KeyMetadataShape|null $keyMetadata + */ + public static function with( + Code|int $code, + Metadata|array $metadata, + Person|array $person, + Status|string $status, + KeyMetadata|array|null $keyMetadata = null, + ): self { + $self = new self; + + $self['code'] = $code; + $self['metadata'] = $metadata; + $self['person'] = $person; + $self['status'] = $status; + + null !== $keyMetadata && $self['keyMetadata'] = $keyMetadata; + + return $self; + } + + /** + * HTTP status code. + * + * @param Code|value-of $code + */ + public function withCode(Code|int $code): self + { + $self = clone $this; + $self['code'] = $code; + + return $self; + } + + /** + * Additional response details. + * + * @param Metadata|MetadataShape $metadata + */ + public function withMetadata(Metadata|array $metadata): self + { + $self = clone $this; + $self['metadata'] = $metadata; + + return $self; + } + + /** + * Retrieved person profile. + * + * @param Person|PersonShape $person + */ + public function withPerson(Person|array $person): self + { + $self = clone $this; + $self['person'] = $person; + + return $self; + } + + /** + * Response status. + * + * @param Status|value-of $status + */ + public function withStatus(Status|string $status): self + { + $self = clone $this; + $self['status'] = $status; + + return $self; + } + + /** + * Metadata about the API key used for the request. Included in every response whenever a valid API key is provided, even when the response status is not 200. + * + * @param KeyMetadata|KeyMetadataShape $keyMetadata + */ + public function withKeyMetadata(KeyMetadata|array $keyMetadata): self + { + $self = clone $this; + $self['keyMetadata'] = $keyMetadata; + + return $self; + } +} diff --git a/src/Batch/BatchSubmitResponse/Code.php b/src/Batch/BatchSubmitResponse/Code.php new file mode 100644 index 0000000..5fa2c30 --- /dev/null +++ b/src/Batch/BatchSubmitResponse/Code.php @@ -0,0 +1,13 @@ + */ + use SdkModel; + + /** + * The number of credits consumed by this request. + */ + #[Required('credits_consumed')] + public int $creditsConsumed; + + /** + * The number of credits remaining for your organization after this request. + */ + #[Required('credits_remaining')] + public int $creditsRemaining; + + /** + * `new KeyMetadata()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * KeyMetadata::with(creditsConsumed: ..., creditsRemaining: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new KeyMetadata)->withCreditsConsumed(...)->withCreditsRemaining(...) + * ``` + */ + 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 $creditsConsumed, + int $creditsRemaining + ): self { + $self = new self; + + $self['creditsConsumed'] = $creditsConsumed; + $self['creditsRemaining'] = $creditsRemaining; + + return $self; + } + + /** + * The number of credits consumed by this request. + */ + public function withCreditsConsumed(int $creditsConsumed): self + { + $self = clone $this; + $self['creditsConsumed'] = $creditsConsumed; + + return $self; + } + + /** + * The number of credits remaining for your organization after this request. + */ + public function withCreditsRemaining(int $creditsRemaining): self + { + $self = clone $this; + $self['creditsRemaining'] = $creditsRemaining; + + return $self; + } +} diff --git a/src/Batch/BatchSubmitResponse/Metadata.php b/src/Batch/BatchSubmitResponse/Metadata.php new file mode 100644 index 0000000..b0fcfa2 --- /dev/null +++ b/src/Batch/BatchSubmitResponse/Metadata.php @@ -0,0 +1,188 @@ +>, + * sourcesSucceeded: list>, + * urlsAnalyzed: list, + * personalWebsiteURL?: string|null, + * } + */ +final class Metadata implements BaseModel +{ + /** @use SdkModel */ + use SdkModel; + + /** + * Identifiers returned for the person. + */ + #[Required] + public Identifiers $identifiers; + + /** + * Source categories checked. + * + * @var list> $sourcesAttempted + */ + #[Required(list: SourcesAttempted::class)] + public array $sourcesAttempted; + + /** + * Source categories with data. + * + * @var list> $sourcesSucceeded + */ + #[Required(list: SourcesSucceeded::class)] + public array $sourcesSucceeded; + + /** + * URLs reviewed for this profile. + * + * @var list $urlsAnalyzed + */ + #[Required(list: 'string')] + public array $urlsAnalyzed; + + /** + * Personal website URL, when found. + */ + #[Optional('personalWebsiteUrl')] + public ?string $personalWebsiteURL; + + /** + * `new Metadata()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * Metadata::with( + * identifiers: ..., + * sourcesAttempted: ..., + * sourcesSucceeded: ..., + * urlsAnalyzed: ..., + * ) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new Metadata) + * ->withIdentifiers(...) + * ->withSourcesAttempted(...) + * ->withSourcesSucceeded(...) + * ->withURLsAnalyzed(...) + * ``` + */ + 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 Identifiers|IdentifiersShape $identifiers + * @param list> $sourcesAttempted + * @param list> $sourcesSucceeded + * @param list $urlsAnalyzed + */ + public static function with( + Identifiers|array $identifiers, + array $sourcesAttempted, + array $sourcesSucceeded, + array $urlsAnalyzed, + ?string $personalWebsiteURL = null, + ): self { + $self = new self; + + $self['identifiers'] = $identifiers; + $self['sourcesAttempted'] = $sourcesAttempted; + $self['sourcesSucceeded'] = $sourcesSucceeded; + $self['urlsAnalyzed'] = $urlsAnalyzed; + + null !== $personalWebsiteURL && $self['personalWebsiteURL'] = $personalWebsiteURL; + + return $self; + } + + /** + * Identifiers returned for the person. + * + * @param Identifiers|IdentifiersShape $identifiers + */ + public function withIdentifiers(Identifiers|array $identifiers): self + { + $self = clone $this; + $self['identifiers'] = $identifiers; + + return $self; + } + + /** + * Source categories checked. + * + * @param list> $sourcesAttempted + */ + public function withSourcesAttempted(array $sourcesAttempted): self + { + $self = clone $this; + $self['sourcesAttempted'] = $sourcesAttempted; + + return $self; + } + + /** + * Source categories with data. + * + * @param list> $sourcesSucceeded + */ + public function withSourcesSucceeded(array $sourcesSucceeded): self + { + $self = clone $this; + $self['sourcesSucceeded'] = $sourcesSucceeded; + + return $self; + } + + /** + * URLs reviewed for this profile. + * + * @param list $urlsAnalyzed + */ + public function withURLsAnalyzed(array $urlsAnalyzed): self + { + $self = clone $this; + $self['urlsAnalyzed'] = $urlsAnalyzed; + + return $self; + } + + /** + * Personal website URL, when found. + */ + public function withPersonalWebsiteURL(string $personalWebsiteURL): self + { + $self = clone $this; + $self['personalWebsiteURL'] = $personalWebsiteURL; + + return $self; + } +} diff --git a/src/Batch/BatchSubmitResponse/Metadata/Identifiers.php b/src/Batch/BatchSubmitResponse/Metadata/Identifiers.php new file mode 100644 index 0000000..21ffd4d --- /dev/null +++ b/src/Batch/BatchSubmitResponse/Metadata/Identifiers.php @@ -0,0 +1,56 @@ + */ + use SdkModel; + + /** + * LinkedIn profile URL. + */ + #[Optional('linkedinUrl')] + public ?string $linkedinURL; + + 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 $linkedinURL = null): self + { + $self = new self; + + null !== $linkedinURL && $self['linkedinURL'] = $linkedinURL; + + return $self; + } + + /** + * LinkedIn profile URL. + */ + public function withLinkedinURL(string $linkedinURL): self + { + $self = clone $this; + $self['linkedinURL'] = $linkedinURL; + + return $self; + } +} diff --git a/src/Batch/BatchSubmitResponse/Metadata/SourcesAttempted.php b/src/Batch/BatchSubmitResponse/Metadata/SourcesAttempted.php new file mode 100644 index 0000000..9b09592 --- /dev/null +++ b/src/Batch/BatchSubmitResponse/Metadata/SourcesAttempted.php @@ -0,0 +1,18 @@ +, + * experience: list, + * profile: Profile|ProfileShape, + * skills: list, + * } + */ +final class Person implements BaseModel +{ + /** @use SdkModel */ + use SdkModel; + + /** + * Education history. + * + * @var list $education + */ + #[Required(list: Education::class)] + public array $education; + + /** + * Work history. + * + * @var list $experience + */ + #[Required(list: Experience::class)] + public array $experience; + + /** + * Core profile details. + */ + #[Required] + public Profile $profile; + + /** + * Listed skills. + * + * @var list $skills + */ + #[Required(list: Skill::class)] + public array $skills; + + /** + * `new Person()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * Person::with(education: ..., experience: ..., profile: ..., skills: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new Person) + * ->withEducation(...) + * ->withExperience(...) + * ->withProfile(...) + * ->withSkills(...) + * ``` + */ + 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 $education + * @param list $experience + * @param Profile|ProfileShape $profile + * @param list $skills + */ + public static function with( + array $education, + array $experience, + Profile|array $profile, + array $skills + ): self { + $self = new self; + + $self['education'] = $education; + $self['experience'] = $experience; + $self['profile'] = $profile; + $self['skills'] = $skills; + + return $self; + } + + /** + * Education history. + * + * @param list $education + */ + public function withEducation(array $education): self + { + $self = clone $this; + $self['education'] = $education; + + return $self; + } + + /** + * Work history. + * + * @param list $experience + */ + public function withExperience(array $experience): self + { + $self = clone $this; + $self['experience'] = $experience; + + return $self; + } + + /** + * Core profile details. + * + * @param Profile|ProfileShape $profile + */ + public function withProfile(Profile|array $profile): self + { + $self = clone $this; + $self['profile'] = $profile; + + return $self; + } + + /** + * Listed skills. + * + * @param list $skills + */ + public function withSkills(array $skills): self + { + $self = clone $this; + $self['skills'] = $skills; + + return $self; + } +} diff --git a/src/Batch/BatchSubmitResponse/Person/Education.php b/src/Batch/BatchSubmitResponse/Person/Education.php new file mode 100644 index 0000000..d6d858d --- /dev/null +++ b/src/Batch/BatchSubmitResponse/Person/Education.php @@ -0,0 +1,165 @@ + */ + use SdkModel; + + /** + * School or institution name. + */ + #[Required] + public Institution $institution; + + /** + * Education dates. + */ + #[Optional] + public ?Dates $dates; + + /** + * Additional education details. + */ + #[Optional] + public ?string $description; + + /** + * Area of study. + */ + #[Optional] + public ?string $fieldOfStudy; + + /** + * Degree, certificate, or credential. + */ + #[Optional] + public ?string $qualification; + + /** + * `new Education()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * Education::with(institution: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new Education)->withInstitution(...) + * ``` + */ + 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 Institution|InstitutionShape $institution + * @param Dates|DatesShape|null $dates + */ + public static function with( + Institution|array $institution, + Dates|array|null $dates = null, + ?string $description = null, + ?string $fieldOfStudy = null, + ?string $qualification = null, + ): self { + $self = new self; + + $self['institution'] = $institution; + + null !== $dates && $self['dates'] = $dates; + null !== $description && $self['description'] = $description; + null !== $fieldOfStudy && $self['fieldOfStudy'] = $fieldOfStudy; + null !== $qualification && $self['qualification'] = $qualification; + + return $self; + } + + /** + * School or institution name. + * + * @param Institution|InstitutionShape $institution + */ + public function withInstitution(Institution|array $institution): self + { + $self = clone $this; + $self['institution'] = $institution; + + return $self; + } + + /** + * Education dates. + * + * @param Dates|DatesShape $dates + */ + public function withDates(Dates|array $dates): self + { + $self = clone $this; + $self['dates'] = $dates; + + return $self; + } + + /** + * Additional education details. + */ + public function withDescription(string $description): self + { + $self = clone $this; + $self['description'] = $description; + + return $self; + } + + /** + * Area of study. + */ + public function withFieldOfStudy(string $fieldOfStudy): self + { + $self = clone $this; + $self['fieldOfStudy'] = $fieldOfStudy; + + return $self; + } + + /** + * Degree, certificate, or credential. + */ + public function withQualification(string $qualification): self + { + $self = clone $this; + $self['qualification'] = $qualification; + + return $self; + } +} diff --git a/src/Batch/BatchSubmitResponse/Person/Education/Dates.php b/src/Batch/BatchSubmitResponse/Person/Education/Dates.php new file mode 100644 index 0000000..64de539 --- /dev/null +++ b/src/Batch/BatchSubmitResponse/Person/Education/Dates.php @@ -0,0 +1,111 @@ + */ + use SdkModel; + + /** + * End date, when known. + */ + #[Optional] + public ?EndDate $endDate; + + /** + * Whether the entry is current. + */ + #[Optional] + public ?bool $isCurrent; + + /** + * Start date, when known. + */ + #[Optional] + public ?StartDate $startDate; + + 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 EndDate|EndDateShape|null $endDate + * @param StartDate|StartDateShape|null $startDate + */ + public static function with( + EndDate|array|null $endDate = null, + ?bool $isCurrent = null, + StartDate|array|null $startDate = null, + ): self { + $self = new self; + + null !== $endDate && $self['endDate'] = $endDate; + null !== $isCurrent && $self['isCurrent'] = $isCurrent; + null !== $startDate && $self['startDate'] = $startDate; + + return $self; + } + + /** + * End date, when known. + * + * @param EndDate|EndDateShape $endDate + */ + public function withEndDate(EndDate|array $endDate): self + { + $self = clone $this; + $self['endDate'] = $endDate; + + return $self; + } + + /** + * Whether the entry is current. + */ + public function withIsCurrent(bool $isCurrent): self + { + $self = clone $this; + $self['isCurrent'] = $isCurrent; + + return $self; + } + + /** + * Start date, when known. + * + * @param StartDate|StartDateShape $startDate + */ + public function withStartDate(StartDate|array $startDate): self + { + $self = clone $this; + $self['startDate'] = $startDate; + + return $self; + } +} diff --git a/src/Batch/BatchSubmitResponse/Person/Education/Dates/EndDate.php b/src/Batch/BatchSubmitResponse/Person/Education/Dates/EndDate.php new file mode 100644 index 0000000..6abd73f --- /dev/null +++ b/src/Batch/BatchSubmitResponse/Person/Education/Dates/EndDate.php @@ -0,0 +1,111 @@ + */ + use SdkModel; + + /** + * Year value. + */ + #[Required] + public int $year; + + /** + * Day value, when known. + */ + #[Optional] + public ?int $day; + + /** + * Month value, when known. + */ + #[Optional] + public ?int $month; + + /** + * `new EndDate()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * EndDate::with(year: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new EndDate)->withYear(...) + * ``` + */ + 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 $year, + ?int $day = null, + ?int $month = null + ): self { + $self = new self; + + $self['year'] = $year; + + null !== $day && $self['day'] = $day; + null !== $month && $self['month'] = $month; + + return $self; + } + + /** + * Year value. + */ + public function withYear(int $year): self + { + $self = clone $this; + $self['year'] = $year; + + return $self; + } + + /** + * Day value, when known. + */ + public function withDay(int $day): self + { + $self = clone $this; + $self['day'] = $day; + + return $self; + } + + /** + * Month value, when known. + */ + public function withMonth(int $month): self + { + $self = clone $this; + $self['month'] = $month; + + return $self; + } +} diff --git a/src/Batch/BatchSubmitResponse/Person/Education/Dates/StartDate.php b/src/Batch/BatchSubmitResponse/Person/Education/Dates/StartDate.php new file mode 100644 index 0000000..356edb2 --- /dev/null +++ b/src/Batch/BatchSubmitResponse/Person/Education/Dates/StartDate.php @@ -0,0 +1,113 @@ + */ + use SdkModel; + + /** + * Year value. + */ + #[Required] + public int $year; + + /** + * Day value, when known. + */ + #[Optional] + public ?int $day; + + /** + * Month value, when known. + */ + #[Optional] + public ?int $month; + + /** + * `new StartDate()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * StartDate::with(year: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new StartDate)->withYear(...) + * ``` + */ + 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 $year, + ?int $day = null, + ?int $month = null + ): self { + $self = new self; + + $self['year'] = $year; + + null !== $day && $self['day'] = $day; + null !== $month && $self['month'] = $month; + + return $self; + } + + /** + * Year value. + */ + public function withYear(int $year): self + { + $self = clone $this; + $self['year'] = $year; + + return $self; + } + + /** + * Day value, when known. + */ + public function withDay(int $day): self + { + $self = clone $this; + $self['day'] = $day; + + return $self; + } + + /** + * Month value, when known. + */ + public function withMonth(int $month): self + { + $self = clone $this; + $self['month'] = $month; + + return $self; + } +} diff --git a/src/Batch/BatchSubmitResponse/Person/Education/Institution.php b/src/Batch/BatchSubmitResponse/Person/Education/Institution.php new file mode 100644 index 0000000..55d16cf --- /dev/null +++ b/src/Batch/BatchSubmitResponse/Person/Education/Institution.php @@ -0,0 +1,94 @@ + */ + use SdkModel; + + /** + * Display name. + */ + #[Required] + public string $display; + + /** + * Standardized name, when available. + */ + #[Optional] + public ?string $normalized; + + /** + * `new Institution()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * Institution::with(display: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new Institution)->withDisplay(...) + * ``` + */ + 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 $display, + ?string $normalized = null + ): self { + $self = new self; + + $self['display'] = $display; + + null !== $normalized && $self['normalized'] = $normalized; + + return $self; + } + + /** + * Display name. + */ + public function withDisplay(string $display): self + { + $self = clone $this; + $self['display'] = $display; + + return $self; + } + + /** + * Standardized name, when available. + */ + public function withNormalized(string $normalized): self + { + $self = clone $this; + $self['normalized'] = $normalized; + + return $self; + } +} diff --git a/src/Batch/BatchSubmitResponse/Person/Experience.php b/src/Batch/BatchSubmitResponse/Person/Experience.php new file mode 100644 index 0000000..b1a0e49 --- /dev/null +++ b/src/Batch/BatchSubmitResponse/Person/Experience.php @@ -0,0 +1,145 @@ + */ + use SdkModel; + + /** + * Company or organization name. + */ + #[Required] + public Company $company; + + /** + * Role or job title. + */ + #[Required] + public string $title; + + /** + * Role dates. + */ + #[Optional] + public ?Dates $dates; + + /** + * Role description. + */ + #[Optional] + public ?string $description; + + /** + * `new Experience()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * Experience::with(company: ..., title: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new Experience)->withCompany(...)->withTitle(...) + * ``` + */ + 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 Company|CompanyShape $company + * @param Dates|DatesShape|null $dates + */ + public static function with( + Company|array $company, + string $title, + Dates|array|null $dates = null, + ?string $description = null, + ): self { + $self = new self; + + $self['company'] = $company; + $self['title'] = $title; + + null !== $dates && $self['dates'] = $dates; + null !== $description && $self['description'] = $description; + + return $self; + } + + /** + * Company or organization name. + * + * @param Company|CompanyShape $company + */ + public function withCompany(Company|array $company): self + { + $self = clone $this; + $self['company'] = $company; + + return $self; + } + + /** + * Role or job title. + */ + public function withTitle(string $title): self + { + $self = clone $this; + $self['title'] = $title; + + return $self; + } + + /** + * Role dates. + * + * @param Dates|DatesShape $dates + */ + public function withDates(Dates|array $dates): self + { + $self = clone $this; + $self['dates'] = $dates; + + return $self; + } + + /** + * Role description. + */ + public function withDescription(string $description): self + { + $self = clone $this; + $self['description'] = $description; + + return $self; + } +} diff --git a/src/Batch/BatchSubmitResponse/Person/Experience/Company.php b/src/Batch/BatchSubmitResponse/Person/Experience/Company.php new file mode 100644 index 0000000..400e046 --- /dev/null +++ b/src/Batch/BatchSubmitResponse/Person/Experience/Company.php @@ -0,0 +1,92 @@ + */ + use SdkModel; + + /** + * Display name. + */ + #[Required] + public string $display; + + /** + * Standardized name, when available. + */ + #[Optional] + public ?string $normalized; + + /** + * `new Company()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * Company::with(display: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new Company)->withDisplay(...) + * ``` + */ + 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 $display, + ?string $normalized = null + ): self { + $self = new self; + + $self['display'] = $display; + + null !== $normalized && $self['normalized'] = $normalized; + + return $self; + } + + /** + * Display name. + */ + public function withDisplay(string $display): self + { + $self = clone $this; + $self['display'] = $display; + + return $self; + } + + /** + * Standardized name, when available. + */ + public function withNormalized(string $normalized): self + { + $self = clone $this; + $self['normalized'] = $normalized; + + return $self; + } +} diff --git a/src/Batch/BatchSubmitResponse/Person/Experience/Dates.php b/src/Batch/BatchSubmitResponse/Person/Experience/Dates.php new file mode 100644 index 0000000..3480d50 --- /dev/null +++ b/src/Batch/BatchSubmitResponse/Person/Experience/Dates.php @@ -0,0 +1,111 @@ + */ + use SdkModel; + + /** + * End date, when known. + */ + #[Optional] + public ?EndDate $endDate; + + /** + * Whether the entry is current. + */ + #[Optional] + public ?bool $isCurrent; + + /** + * Start date, when known. + */ + #[Optional] + public ?StartDate $startDate; + + 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 EndDate|EndDateShape|null $endDate + * @param StartDate|StartDateShape|null $startDate + */ + public static function with( + EndDate|array|null $endDate = null, + ?bool $isCurrent = null, + StartDate|array|null $startDate = null, + ): self { + $self = new self; + + null !== $endDate && $self['endDate'] = $endDate; + null !== $isCurrent && $self['isCurrent'] = $isCurrent; + null !== $startDate && $self['startDate'] = $startDate; + + return $self; + } + + /** + * End date, when known. + * + * @param EndDate|EndDateShape $endDate + */ + public function withEndDate(EndDate|array $endDate): self + { + $self = clone $this; + $self['endDate'] = $endDate; + + return $self; + } + + /** + * Whether the entry is current. + */ + public function withIsCurrent(bool $isCurrent): self + { + $self = clone $this; + $self['isCurrent'] = $isCurrent; + + return $self; + } + + /** + * Start date, when known. + * + * @param StartDate|StartDateShape $startDate + */ + public function withStartDate(StartDate|array $startDate): self + { + $self = clone $this; + $self['startDate'] = $startDate; + + return $self; + } +} diff --git a/src/Batch/BatchSubmitResponse/Person/Experience/Dates/EndDate.php b/src/Batch/BatchSubmitResponse/Person/Experience/Dates/EndDate.php new file mode 100644 index 0000000..9723146 --- /dev/null +++ b/src/Batch/BatchSubmitResponse/Person/Experience/Dates/EndDate.php @@ -0,0 +1,111 @@ + */ + use SdkModel; + + /** + * Year value. + */ + #[Required] + public int $year; + + /** + * Day value, when known. + */ + #[Optional] + public ?int $day; + + /** + * Month value, when known. + */ + #[Optional] + public ?int $month; + + /** + * `new EndDate()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * EndDate::with(year: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new EndDate)->withYear(...) + * ``` + */ + 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 $year, + ?int $day = null, + ?int $month = null + ): self { + $self = new self; + + $self['year'] = $year; + + null !== $day && $self['day'] = $day; + null !== $month && $self['month'] = $month; + + return $self; + } + + /** + * Year value. + */ + public function withYear(int $year): self + { + $self = clone $this; + $self['year'] = $year; + + return $self; + } + + /** + * Day value, when known. + */ + public function withDay(int $day): self + { + $self = clone $this; + $self['day'] = $day; + + return $self; + } + + /** + * Month value, when known. + */ + public function withMonth(int $month): self + { + $self = clone $this; + $self['month'] = $month; + + return $self; + } +} diff --git a/src/Batch/BatchSubmitResponse/Person/Experience/Dates/StartDate.php b/src/Batch/BatchSubmitResponse/Person/Experience/Dates/StartDate.php new file mode 100644 index 0000000..a8a241d --- /dev/null +++ b/src/Batch/BatchSubmitResponse/Person/Experience/Dates/StartDate.php @@ -0,0 +1,113 @@ + */ + use SdkModel; + + /** + * Year value. + */ + #[Required] + public int $year; + + /** + * Day value, when known. + */ + #[Optional] + public ?int $day; + + /** + * Month value, when known. + */ + #[Optional] + public ?int $month; + + /** + * `new StartDate()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * StartDate::with(year: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new StartDate)->withYear(...) + * ``` + */ + 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 $year, + ?int $day = null, + ?int $month = null + ): self { + $self = new self; + + $self['year'] = $year; + + null !== $day && $self['day'] = $day; + null !== $month && $self['month'] = $month; + + return $self; + } + + /** + * Year value. + */ + public function withYear(int $year): self + { + $self = clone $this; + $self['year'] = $year; + + return $self; + } + + /** + * Day value, when known. + */ + public function withDay(int $day): self + { + $self = clone $this; + $self['day'] = $day; + + return $self; + } + + /** + * Month value, when known. + */ + public function withMonth(int $month): self + { + $self = clone $this; + $self['month'] = $month; + + return $self; + } +} diff --git a/src/Batch/BatchSubmitResponse/Person/Profile.php b/src/Batch/BatchSubmitResponse/Person/Profile.php new file mode 100644 index 0000000..fb6274e --- /dev/null +++ b/src/Batch/BatchSubmitResponse/Person/Profile.php @@ -0,0 +1,139 @@ + */ + use SdkModel; + + /** + * Person's full name. + */ + #[Optional] + public ?string $fullName; + + /** + * Short professional headline. + */ + #[Optional] + public ?string $headline; + + /** + * Person's listed location. + */ + #[Optional] + public ?string $location; + + /** + * Profile image URL. + */ + #[Optional('profilePictureUrl')] + public ?string $profilePictureURL; + + /** + * Brief profile summary. + */ + #[Optional] + public ?string $summary; + + 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 $fullName = null, + ?string $headline = null, + ?string $location = null, + ?string $profilePictureURL = null, + ?string $summary = null, + ): self { + $self = new self; + + null !== $fullName && $self['fullName'] = $fullName; + null !== $headline && $self['headline'] = $headline; + null !== $location && $self['location'] = $location; + null !== $profilePictureURL && $self['profilePictureURL'] = $profilePictureURL; + null !== $summary && $self['summary'] = $summary; + + return $self; + } + + /** + * Person's full name. + */ + public function withFullName(string $fullName): self + { + $self = clone $this; + $self['fullName'] = $fullName; + + return $self; + } + + /** + * Short professional headline. + */ + public function withHeadline(string $headline): self + { + $self = clone $this; + $self['headline'] = $headline; + + return $self; + } + + /** + * Person's listed location. + */ + public function withLocation(string $location): self + { + $self = clone $this; + $self['location'] = $location; + + return $self; + } + + /** + * Profile image URL. + */ + public function withProfilePictureURL(string $profilePictureURL): self + { + $self = clone $this; + $self['profilePictureURL'] = $profilePictureURL; + + return $self; + } + + /** + * Brief profile summary. + */ + public function withSummary(string $summary): self + { + $self = clone $this; + $self['summary'] = $summary; + + return $self; + } +} diff --git a/src/Batch/BatchSubmitResponse/Person/Skill.php b/src/Batch/BatchSubmitResponse/Person/Skill.php new file mode 100644 index 0000000..b5e9c82 --- /dev/null +++ b/src/Batch/BatchSubmitResponse/Person/Skill.php @@ -0,0 +1,111 @@ + */ + use SdkModel; + + /** + * Skill name. + */ + #[Required] + public string $name; + + /** + * Standardized skill name, when available. + */ + #[Optional] + public ?string $normalized; + + /** + * Skill proficiency, when available. + */ + #[Optional] + public ?string $proficiency; + + /** + * `new Skill()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * Skill::with(name: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new Skill)->withName(...) + * ``` + */ + 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 $name, + ?string $normalized = null, + ?string $proficiency = null + ): self { + $self = new self; + + $self['name'] = $name; + + null !== $normalized && $self['normalized'] = $normalized; + null !== $proficiency && $self['proficiency'] = $proficiency; + + return $self; + } + + /** + * Skill name. + */ + public function withName(string $name): self + { + $self = clone $this; + $self['name'] = $name; + + return $self; + } + + /** + * Standardized skill name, when available. + */ + public function withNormalized(string $normalized): self + { + $self = clone $this; + $self['normalized'] = $normalized; + + return $self; + } + + /** + * Skill proficiency, when available. + */ + public function withProficiency(string $proficiency): self + { + $self = clone $this; + $self['proficiency'] = $proficiency; + + return $self; + } +} diff --git a/src/Batch/BatchSubmitResponse/Status.php b/src/Batch/BatchSubmitResponse/Status.php new file mode 100644 index 0000000..e71e05d --- /dev/null +++ b/src/Batch/BatchSubmitResponse/Status.php @@ -0,0 +1,13 @@ + */ + use SdkModel; + + /** + * Batch error code. + */ + #[Required] + public string $code; + + /** + * Batch error message. + */ + #[Required] + public string $message; + + /** + * `new Error()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * Error::with(code: ..., message: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new Error)->withCode(...)->withMessage(...) + * ``` + */ + public function __construct() + { + $this->initialize(); + } + + /** + * Construct an instance from the required parameters. + * + * You must use named parameters to construct any parameters with a default value. + */ + public static function with(string $code, string $message): self + { + $self = new self; + + $self['code'] = $code; + $self['message'] = $message; + + return $self; + } + + /** + * Batch error code. + */ + public function withCode(string $code): self + { + $self = clone $this; + $self['code'] = $code; + + return $self; + } + + /** + * Batch error message. + */ + public function withMessage(string $message): self + { + $self = clone $this; + $self['message'] = $message; + + return $self; + } +} diff --git a/src/Batch/ErrorCount.php b/src/Batch/ErrorCount.php new file mode 100644 index 0000000..3f34bb8 --- /dev/null +++ b/src/Batch/ErrorCount.php @@ -0,0 +1,88 @@ + */ + use SdkModel; + + /** + * Error code for these failures. + */ + #[Required] + public string $code; + + /** + * Pages that failed with this code. + */ + #[Required] + public int $count; + + /** + * `new ErrorCount()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * ErrorCount::with(code: ..., count: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new ErrorCount)->withCode(...)->withCount(...) + * ``` + */ + public function __construct() + { + $this->initialize(); + } + + /** + * Construct an instance from the required parameters. + * + * You must use named parameters to construct any parameters with a default value. + */ + public static function with(string $code, int $count): self + { + $self = new self; + + $self['code'] = $code; + $self['count'] = $count; + + return $self; + } + + /** + * Error code for these failures. + */ + public function withCode(string $code): self + { + $self = clone $this; + $self['code'] = $code; + + return $self; + } + + /** + * Pages that failed with this code. + */ + public function withCount(int $count): self + { + $self = clone $this; + $self['count'] = $count; + + return $self; + } +} diff --git a/src/Client.php b/src/Client.php index f7d5f17..2258fbc 100644 --- a/src/Client.php +++ b/src/Client.php @@ -8,6 +8,7 @@ use ContextDev\Core\Implementation\StreamingHttpClient; use ContextDev\Core\Util; use ContextDev\Services\AIService; +use ContextDev\Services\BatchService; use ContextDev\Services\BrandService; use ContextDev\Services\IndustryService; use ContextDev\Services\MonitorsService; @@ -60,6 +61,11 @@ class Client extends BaseClient */ public MonitorsService $monitors; + /** + * @api + */ + public BatchService $batch; + /** * @param RequestOpts|null $requestOptions */ @@ -125,6 +131,7 @@ public function __construct( $this->industry = new IndustryService($this); $this->utility = new UtilityService($this); $this->monitors = new MonitorsService($this); + $this->batch = new BatchService($this); } /** @return array */ diff --git a/src/Monitors/MonitorCreateParams.php b/src/Monitors/MonitorCreateParams.php index 56eec6e..6786369 100644 --- a/src/Monitors/MonitorCreateParams.php +++ b/src/Monitors/MonitorCreateParams.php @@ -25,19 +25,19 @@ * * @see ContextDev\Services\MonitorsService::create() * - * @phpstan-import-type ChangeDetectionVariants from \ContextDev\Monitors\MonitorCreateParams\ChangeDetection * @phpstan-import-type TargetVariants from \ContextDev\Monitors\MonitorCreateParams\Target + * @phpstan-import-type ChangeDetectionVariants from \ContextDev\Monitors\MonitorCreateParams\ChangeDetection + * @phpstan-import-type TargetShape from \ContextDev\Monitors\MonitorCreateParams\Target * @phpstan-import-type ChangeDetectionShape from \ContextDev\Monitors\MonitorCreateParams\ChangeDetection * @phpstan-import-type ScheduleShape from \ContextDev\Monitors\MonitorCreateParams\Schedule - * @phpstan-import-type TargetShape from \ContextDev\Monitors\MonitorCreateParams\Target * @phpstan-import-type WebhookShape from \ContextDev\Monitors\MonitorCreateParams\Webhook * * @phpstan-type MonitorCreateParamsShape = array{ - * changeDetection: ChangeDetectionShape, * name: string, - * schedule: Schedule|ScheduleShape, * target: TargetShape, + * changeDetection?: ChangeDetectionShape|null, * mode?: null|Mode|value-of, + * schedule?: null|Schedule|ScheduleShape, * tags?: list|null, * webhook?: null|Webhook|WebhookShape, * } @@ -48,23 +48,9 @@ final class MonitorCreateParams implements BaseModel use SdkModel; use SdkParams; - /** - * Discriminated union describing how changes are detected. - * - * @var ChangeDetectionVariants $changeDetection - */ - #[Required('change_detection', union: ChangeDetection::class)] - public MonitorsExactChangeDetection|MonitorsSemanticChangeDetection $changeDetection; - #[Required] public string $name; - /** - * 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. - */ - #[Required] - public Schedule $schedule; - /** * Discriminated union describing what the monitor watches. * @@ -73,6 +59,14 @@ final class MonitorCreateParams implements BaseModel #[Required(union: Target::class)] public MonitorsPageTarget|MonitorsSitemapTarget|MonitorsExtractTarget $target; + /** + * Discriminated union describing how changes are detected. + * + * @var ChangeDetectionVariants|null $changeDetection + */ + #[Optional('change_detection', union: ChangeDetection::class)] + public MonitorsExactChangeDetection|MonitorsSemanticChangeDetection|null $changeDetection; + /** * Top-level monitor category. Always `web` today; the concrete behavior is described by `target` and `change_detection`. * @@ -81,6 +75,12 @@ final class MonitorCreateParams implements BaseModel #[Optional(enum: Mode::class)] public ?string $mode; + /** + * 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. + */ + #[Optional] + public ?Schedule $schedule; + /** * User-defined tags for grouping and filtering monitors and their changes. Duplicates are removed. * @@ -97,19 +97,13 @@ final class MonitorCreateParams implements BaseModel * * To enforce required parameters use * ``` - * MonitorCreateParams::with( - * changeDetection: ..., name: ..., schedule: ..., target: ... - * ) + * MonitorCreateParams::with(name: ..., target: ...) * ``` * * Otherwise ensure the following setters are called * * ``` - * (new MonitorCreateParams) - * ->withChangeDetection(...) - * ->withName(...) - * ->withSchedule(...) - * ->withTarget(...) + * (new MonitorCreateParams)->withName(...)->withTarget(...) * ``` */ public function __construct() @@ -122,50 +116,36 @@ public function __construct() * * You must use named parameters to construct any parameters with a default value. * - * @param ChangeDetectionShape $changeDetection - * @param Schedule|ScheduleShape $schedule * @param TargetShape $target + * @param ChangeDetectionShape|null $changeDetection * @param Mode|value-of|null $mode + * @param Schedule|ScheduleShape|null $schedule * @param list|null $tags * @param Webhook|WebhookShape|null $webhook */ public static function with( - MonitorsExactChangeDetection|array|MonitorsSemanticChangeDetection $changeDetection, string $name, - Schedule|array $schedule, MonitorsPageTarget|array|MonitorsSitemapTarget|MonitorsExtractTarget $target, + MonitorsExactChangeDetection|array|MonitorsSemanticChangeDetection|null $changeDetection = null, Mode|string|null $mode = null, + Schedule|array|null $schedule = null, ?array $tags = null, Webhook|array|null $webhook = null, ): self { $self = new self; - $self['changeDetection'] = $changeDetection; $self['name'] = $name; - $self['schedule'] = $schedule; $self['target'] = $target; + null !== $changeDetection && $self['changeDetection'] = $changeDetection; null !== $mode && $self['mode'] = $mode; + null !== $schedule && $self['schedule'] = $schedule; null !== $tags && $self['tags'] = $tags; null !== $webhook && $self['webhook'] = $webhook; return $self; } - /** - * Discriminated union describing how changes are detected. - * - * @param ChangeDetectionShape $changeDetection - */ - public function withChangeDetection( - MonitorsExactChangeDetection|array|MonitorsSemanticChangeDetection $changeDetection, - ): self { - $self = clone $this; - $self['changeDetection'] = $changeDetection; - - return $self; - } - public function withName(string $name): self { $self = clone $this; @@ -175,28 +155,29 @@ public function withName(string $name): self } /** - * 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. + * Discriminated union describing what the monitor watches. * - * @param Schedule|ScheduleShape $schedule + * @param TargetShape $target */ - public function withSchedule(Schedule|array $schedule): self - { + public function withTarget( + MonitorsPageTarget|array|MonitorsSitemapTarget|MonitorsExtractTarget $target + ): self { $self = clone $this; - $self['schedule'] = $schedule; + $self['target'] = $target; return $self; } /** - * Discriminated union describing what the monitor watches. + * Discriminated union describing how changes are detected. * - * @param TargetShape $target + * @param ChangeDetectionShape $changeDetection */ - public function withTarget( - MonitorsPageTarget|array|MonitorsSitemapTarget|MonitorsExtractTarget $target + public function withChangeDetection( + MonitorsExactChangeDetection|array|MonitorsSemanticChangeDetection $changeDetection, ): self { $self = clone $this; - $self['target'] = $target; + $self['changeDetection'] = $changeDetection; return $self; } @@ -214,6 +195,19 @@ public function withMode(Mode|string $mode): self return $self; } + /** + * 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 Schedule|ScheduleShape $schedule + */ + public function withSchedule(Schedule|array $schedule): self + { + $self = clone $this; + $self['schedule'] = $schedule; + + return $self; + } + /** * User-defined tags for grouping and filtering monitors and their changes. Duplicates are removed. * diff --git a/src/Monitors/MonitorCreateParams/ChangeDetection/MonitorsSemanticChangeDetection.php b/src/Monitors/MonitorCreateParams/ChangeDetection/MonitorsSemanticChangeDetection.php index 2f32c23..a986e3e 100644 --- a/src/Monitors/MonitorCreateParams/ChangeDetection/MonitorsSemanticChangeDetection.php +++ b/src/Monitors/MonitorCreateParams/ChangeDetection/MonitorsSemanticChangeDetection.php @@ -10,7 +10,7 @@ use ContextDev\Core\Contracts\BaseModel; /** - * Detect meaning-level changes to tracked page content, ignoring cosmetic or paraphrase-only differences. Which changes are meaningful is judged against the extract target's `instructions` (and `schema`, when provided). + * Detect meaning-level changes to page content, ignoring cosmetic or instruction-irrelevant differences. Which changes are meaningful is judged against the page or extract target's `instructions` (and an extract target's `schema`, when provided). * * @phpstan-type MonitorsSemanticChangeDetectionShape = array{ * type: 'semantic', confidenceThreshold?: float|null diff --git a/src/Monitors/MonitorCreateParams/Target/MonitorsPageTarget.php b/src/Monitors/MonitorCreateParams/Target/MonitorsPageTarget.php index c5908ac..bc4b982 100644 --- a/src/Monitors/MonitorCreateParams/Target/MonitorsPageTarget.php +++ b/src/Monitors/MonitorCreateParams/Target/MonitorsPageTarget.php @@ -10,10 +10,13 @@ use ContextDev\Core\Contracts\BaseModel; /** - * Watch a single web page. + * Watch a single web page. Exact detection reports visible-text diffs; semantic detection judges confirmed stable diffs against `instructions`. * * @phpstan-type MonitorsPageTargetShape = array{ - * type: 'page', url: string, normalizeWhitespace?: bool|null + * type: 'page', + * url: string, + * instructions?: string|null, + * normalizeWhitespace?: bool|null, * } */ final class MonitorsPageTarget implements BaseModel @@ -28,6 +31,12 @@ final class MonitorsPageTarget implements BaseModel #[Required] public string $url; + /** + * Plain-language goal describing which page changes matter. When provided without change_detection, semantic detection is inferred. + */ + #[Optional] + public ?string $instructions; + /** * Normalize whitespace before comparing or analyzing text. */ @@ -60,12 +69,14 @@ public function __construct() */ public static function with( string $url, + ?string $instructions = null, ?bool $normalizeWhitespace = null ): self { $self = new self; $self['url'] = $url; + null !== $instructions && $self['instructions'] = $instructions; null !== $normalizeWhitespace && $self['normalizeWhitespace'] = $normalizeWhitespace; return $self; @@ -90,6 +101,17 @@ public function withURL(string $url): self return $self; } + /** + * Plain-language goal describing which page changes matter. When provided without change_detection, semantic detection is inferred. + */ + public function withInstructions(string $instructions): self + { + $self = clone $this; + $self['instructions'] = $instructions; + + return $self; + } + /** * Normalize whitespace before comparing or analyzing text. */ diff --git a/src/Monitors/MonitorGetResponse/ChangeDetection/MonitorsSemanticChangeDetection.php b/src/Monitors/MonitorGetResponse/ChangeDetection/MonitorsSemanticChangeDetection.php index 1fe50cb..45361f5 100644 --- a/src/Monitors/MonitorGetResponse/ChangeDetection/MonitorsSemanticChangeDetection.php +++ b/src/Monitors/MonitorGetResponse/ChangeDetection/MonitorsSemanticChangeDetection.php @@ -10,7 +10,7 @@ use ContextDev\Core\Contracts\BaseModel; /** - * Detect meaning-level changes to tracked page content, ignoring cosmetic or paraphrase-only differences. Which changes are meaningful is judged against the extract target's `instructions` (and `schema`, when provided). + * Detect meaning-level changes to page content, ignoring cosmetic or instruction-irrelevant differences. Which changes are meaningful is judged against the page or extract target's `instructions` (and an extract target's `schema`, when provided). * * @phpstan-type MonitorsSemanticChangeDetectionShape = array{ * type: 'semantic', confidenceThreshold?: float|null diff --git a/src/Monitors/MonitorGetResponse/Target/MonitorsPageTarget.php b/src/Monitors/MonitorGetResponse/Target/MonitorsPageTarget.php index 0689dc3..5252039 100644 --- a/src/Monitors/MonitorGetResponse/Target/MonitorsPageTarget.php +++ b/src/Monitors/MonitorGetResponse/Target/MonitorsPageTarget.php @@ -10,10 +10,13 @@ use ContextDev\Core\Contracts\BaseModel; /** - * Watch a single web page. + * Watch a single web page. Exact detection reports visible-text diffs; semantic detection judges confirmed stable diffs against `instructions`. * * @phpstan-type MonitorsPageTargetShape = array{ - * type: 'page', url: string, normalizeWhitespace?: bool|null + * type: 'page', + * url: string, + * instructions?: string|null, + * normalizeWhitespace?: bool|null, * } */ final class MonitorsPageTarget implements BaseModel @@ -28,6 +31,12 @@ final class MonitorsPageTarget implements BaseModel #[Required] public string $url; + /** + * Plain-language goal describing which page changes matter. When provided without change_detection, semantic detection is inferred. + */ + #[Optional] + public ?string $instructions; + /** * Normalize whitespace before comparing or analyzing text. */ @@ -60,12 +69,14 @@ public function __construct() */ public static function with( string $url, + ?string $instructions = null, ?bool $normalizeWhitespace = null ): self { $self = new self; $self['url'] = $url; + null !== $instructions && $self['instructions'] = $instructions; null !== $normalizeWhitespace && $self['normalizeWhitespace'] = $normalizeWhitespace; return $self; @@ -90,6 +101,17 @@ public function withURL(string $url): self return $self; } + /** + * Plain-language goal describing which page changes matter. When provided without change_detection, semantic detection is inferred. + */ + public function withInstructions(string $instructions): self + { + $self = clone $this; + $self['instructions'] = $instructions; + + return $self; + } + /** * Normalize whitespace before comparing or analyzing text. */ diff --git a/src/Monitors/MonitorListResponse/Data/ChangeDetection/MonitorsSemanticChangeDetection.php b/src/Monitors/MonitorListResponse/Data/ChangeDetection/MonitorsSemanticChangeDetection.php index bf1868d..711853a 100644 --- a/src/Monitors/MonitorListResponse/Data/ChangeDetection/MonitorsSemanticChangeDetection.php +++ b/src/Monitors/MonitorListResponse/Data/ChangeDetection/MonitorsSemanticChangeDetection.php @@ -10,7 +10,7 @@ use ContextDev\Core\Contracts\BaseModel; /** - * Detect meaning-level changes to tracked page content, ignoring cosmetic or paraphrase-only differences. Which changes are meaningful is judged against the extract target's `instructions` (and `schema`, when provided). + * Detect meaning-level changes to page content, ignoring cosmetic or instruction-irrelevant differences. Which changes are meaningful is judged against the page or extract target's `instructions` (and an extract target's `schema`, when provided). * * @phpstan-type MonitorsSemanticChangeDetectionShape = array{ * type: 'semantic', confidenceThreshold?: float|null diff --git a/src/Monitors/MonitorListResponse/Data/Target/MonitorsPageTarget.php b/src/Monitors/MonitorListResponse/Data/Target/MonitorsPageTarget.php index bff0489..b059142 100644 --- a/src/Monitors/MonitorListResponse/Data/Target/MonitorsPageTarget.php +++ b/src/Monitors/MonitorListResponse/Data/Target/MonitorsPageTarget.php @@ -10,10 +10,13 @@ use ContextDev\Core\Contracts\BaseModel; /** - * Watch a single web page. + * Watch a single web page. Exact detection reports visible-text diffs; semantic detection judges confirmed stable diffs against `instructions`. * * @phpstan-type MonitorsPageTargetShape = array{ - * type: 'page', url: string, normalizeWhitespace?: bool|null + * type: 'page', + * url: string, + * instructions?: string|null, + * normalizeWhitespace?: bool|null, * } */ final class MonitorsPageTarget implements BaseModel @@ -28,6 +31,12 @@ final class MonitorsPageTarget implements BaseModel #[Required] public string $url; + /** + * Plain-language goal describing which page changes matter. When provided without change_detection, semantic detection is inferred. + */ + #[Optional] + public ?string $instructions; + /** * Normalize whitespace before comparing or analyzing text. */ @@ -60,12 +69,14 @@ public function __construct() */ public static function with( string $url, + ?string $instructions = null, ?bool $normalizeWhitespace = null ): self { $self = new self; $self['url'] = $url; + null !== $instructions && $self['instructions'] = $instructions; null !== $normalizeWhitespace && $self['normalizeWhitespace'] = $normalizeWhitespace; return $self; @@ -90,6 +101,17 @@ public function withURL(string $url): self return $self; } + /** + * Plain-language goal describing which page changes matter. When provided without change_detection, semantic detection is inferred. + */ + public function withInstructions(string $instructions): self + { + $self = clone $this; + $self['instructions'] = $instructions; + + return $self; + } + /** * Normalize whitespace before comparing or analyzing text. */ diff --git a/src/Monitors/MonitorNewResponse.php b/src/Monitors/MonitorNewResponse.php index d70d44e..809d822 100644 --- a/src/Monitors/MonitorNewResponse.php +++ b/src/Monitors/MonitorNewResponse.php @@ -26,7 +26,7 @@ use ContextDev\Monitors\MonitorNewResponse\WebhookFailure; /** - * A web monitor. `mode` is the constant `web`; behavior is described by `target` (page/sitemap/extract) and `change_detection` (exact/semantic). + * A newly created monitor plus `initial_run_id`, the id of the baseline run queued at creation. * * @phpstan-import-type ChangeDetectionVariants from \ContextDev\Monitors\MonitorNewResponse\ChangeDetection * @phpstan-import-type TargetVariants from \ContextDev\Monitors\MonitorNewResponse\Target @@ -43,6 +43,7 @@ * id: string, * changeDetection: ChangeDetectionShape, * createdAt: \DateTimeInterface, + * initialRunID: string|null, * mode: Mode|value-of, * name: string, * schedule: Schedule|ScheduleShape, @@ -78,6 +79,12 @@ final class MonitorNewResponse implements BaseModel #[Required('created_at')] public \DateTimeInterface $createdAt; + /** + * The baseline run queued by this create call, or null if it could not be queued immediately (in which case the baseline runs on the next scheduled tick). Poll GET /monitors/{monitor_id}/runs/{run_id}. + */ + #[Required('initial_run_id')] + public ?string $initialRunID; + /** * Top-level monitor category. Always `web` today; the concrete behavior is described by `target` and `change_detection`. * @@ -166,6 +173,7 @@ final class MonitorNewResponse implements BaseModel * id: ..., * changeDetection: ..., * createdAt: ..., + * initialRunID: ..., * mode: ..., * name: ..., * schedule: ..., @@ -182,6 +190,7 @@ final class MonitorNewResponse implements BaseModel * ->withID(...) * ->withChangeDetection(...) * ->withCreatedAt(...) + * ->withInitialRunID(...) * ->withMode(...) * ->withName(...) * ->withSchedule(...) @@ -215,6 +224,7 @@ public static function with( string $id, MonitorsExactChangeDetection|array|MonitorsSemanticChangeDetection $changeDetection, \DateTimeInterface $createdAt, + ?string $initialRunID, Mode|string $mode, string $name, Schedule|array $schedule, @@ -235,6 +245,7 @@ public static function with( $self['id'] = $id; $self['changeDetection'] = $changeDetection; $self['createdAt'] = $createdAt; + $self['initialRunID'] = $initialRunID; $self['mode'] = $mode; $self['name'] = $name; $self['schedule'] = $schedule; @@ -284,6 +295,17 @@ public function withCreatedAt(\DateTimeInterface $createdAt): self return $self; } + /** + * The baseline run queued by this create call, or null if it could not be queued immediately (in which case the baseline runs on the next scheduled tick). Poll GET /monitors/{monitor_id}/runs/{run_id}. + */ + public function withInitialRunID(?string $initialRunID): self + { + $self = clone $this; + $self['initialRunID'] = $initialRunID; + + return $self; + } + /** * Top-level monitor category. Always `web` today; the concrete behavior is described by `target` and `change_detection`. * diff --git a/src/Monitors/MonitorNewResponse/ChangeDetection/MonitorsSemanticChangeDetection.php b/src/Monitors/MonitorNewResponse/ChangeDetection/MonitorsSemanticChangeDetection.php index 9ca859f..010fea7 100644 --- a/src/Monitors/MonitorNewResponse/ChangeDetection/MonitorsSemanticChangeDetection.php +++ b/src/Monitors/MonitorNewResponse/ChangeDetection/MonitorsSemanticChangeDetection.php @@ -10,7 +10,7 @@ use ContextDev\Core\Contracts\BaseModel; /** - * Detect meaning-level changes to tracked page content, ignoring cosmetic or paraphrase-only differences. Which changes are meaningful is judged against the extract target's `instructions` (and `schema`, when provided). + * Detect meaning-level changes to page content, ignoring cosmetic or instruction-irrelevant differences. Which changes are meaningful is judged against the page or extract target's `instructions` (and an extract target's `schema`, when provided). * * @phpstan-type MonitorsSemanticChangeDetectionShape = array{ * type: 'semantic', confidenceThreshold?: float|null diff --git a/src/Monitors/MonitorNewResponse/Target/MonitorsPageTarget.php b/src/Monitors/MonitorNewResponse/Target/MonitorsPageTarget.php index cb684a9..56c8a61 100644 --- a/src/Monitors/MonitorNewResponse/Target/MonitorsPageTarget.php +++ b/src/Monitors/MonitorNewResponse/Target/MonitorsPageTarget.php @@ -10,10 +10,13 @@ use ContextDev\Core\Contracts\BaseModel; /** - * Watch a single web page. + * Watch a single web page. Exact detection reports visible-text diffs; semantic detection judges confirmed stable diffs against `instructions`. * * @phpstan-type MonitorsPageTargetShape = array{ - * type: 'page', url: string, normalizeWhitespace?: bool|null + * type: 'page', + * url: string, + * instructions?: string|null, + * normalizeWhitespace?: bool|null, * } */ final class MonitorsPageTarget implements BaseModel @@ -28,6 +31,12 @@ final class MonitorsPageTarget implements BaseModel #[Required] public string $url; + /** + * Plain-language goal describing which page changes matter. When provided without change_detection, semantic detection is inferred. + */ + #[Optional] + public ?string $instructions; + /** * Normalize whitespace before comparing or analyzing text. */ @@ -60,12 +69,14 @@ public function __construct() */ public static function with( string $url, + ?string $instructions = null, ?bool $normalizeWhitespace = null ): self { $self = new self; $self['url'] = $url; + null !== $instructions && $self['instructions'] = $instructions; null !== $normalizeWhitespace && $self['normalizeWhitespace'] = $normalizeWhitespace; return $self; @@ -90,6 +101,17 @@ public function withURL(string $url): self return $self; } + /** + * Plain-language goal describing which page changes matter. When provided without change_detection, semantic detection is inferred. + */ + public function withInstructions(string $instructions): self + { + $self = clone $this; + $self['instructions'] = $instructions; + + return $self; + } + /** * Normalize whitespace before comparing or analyzing text. */ diff --git a/src/Monitors/MonitorUpdateParams/ChangeDetection/MonitorsSemanticChangeDetection.php b/src/Monitors/MonitorUpdateParams/ChangeDetection/MonitorsSemanticChangeDetection.php index b25c452..8b75978 100644 --- a/src/Monitors/MonitorUpdateParams/ChangeDetection/MonitorsSemanticChangeDetection.php +++ b/src/Monitors/MonitorUpdateParams/ChangeDetection/MonitorsSemanticChangeDetection.php @@ -10,7 +10,7 @@ use ContextDev\Core\Contracts\BaseModel; /** - * Detect meaning-level changes to tracked page content, ignoring cosmetic or paraphrase-only differences. Which changes are meaningful is judged against the extract target's `instructions` (and `schema`, when provided). + * Detect meaning-level changes to page content, ignoring cosmetic or instruction-irrelevant differences. Which changes are meaningful is judged against the page or extract target's `instructions` (and an extract target's `schema`, when provided). * * @phpstan-type MonitorsSemanticChangeDetectionShape = array{ * type: 'semantic', confidenceThreshold?: float|null diff --git a/src/Monitors/MonitorUpdateParams/Target/MonitorsPageTarget.php b/src/Monitors/MonitorUpdateParams/Target/MonitorsPageTarget.php index 6e4bf1e..a86aa19 100644 --- a/src/Monitors/MonitorUpdateParams/Target/MonitorsPageTarget.php +++ b/src/Monitors/MonitorUpdateParams/Target/MonitorsPageTarget.php @@ -10,10 +10,13 @@ use ContextDev\Core\Contracts\BaseModel; /** - * Watch a single web page. + * Watch a single web page. Exact detection reports visible-text diffs; semantic detection judges confirmed stable diffs against `instructions`. * * @phpstan-type MonitorsPageTargetShape = array{ - * type: 'page', url: string, normalizeWhitespace?: bool|null + * type: 'page', + * url: string, + * instructions?: string|null, + * normalizeWhitespace?: bool|null, * } */ final class MonitorsPageTarget implements BaseModel @@ -28,6 +31,12 @@ final class MonitorsPageTarget implements BaseModel #[Required] public string $url; + /** + * Plain-language goal describing which page changes matter. When provided without change_detection, semantic detection is inferred. + */ + #[Optional] + public ?string $instructions; + /** * Normalize whitespace before comparing or analyzing text. */ @@ -60,12 +69,14 @@ public function __construct() */ public static function with( string $url, + ?string $instructions = null, ?bool $normalizeWhitespace = null ): self { $self = new self; $self['url'] = $url; + null !== $instructions && $self['instructions'] = $instructions; null !== $normalizeWhitespace && $self['normalizeWhitespace'] = $normalizeWhitespace; return $self; @@ -90,6 +101,17 @@ public function withURL(string $url): self return $self; } + /** + * Plain-language goal describing which page changes matter. When provided without change_detection, semantic detection is inferred. + */ + public function withInstructions(string $instructions): self + { + $self = clone $this; + $self['instructions'] = $instructions; + + return $self; + } + /** * Normalize whitespace before comparing or analyzing text. */ diff --git a/src/Monitors/MonitorUpdateResponse/ChangeDetection/MonitorsSemanticChangeDetection.php b/src/Monitors/MonitorUpdateResponse/ChangeDetection/MonitorsSemanticChangeDetection.php index c1ccfc6..9c22a5e 100644 --- a/src/Monitors/MonitorUpdateResponse/ChangeDetection/MonitorsSemanticChangeDetection.php +++ b/src/Monitors/MonitorUpdateResponse/ChangeDetection/MonitorsSemanticChangeDetection.php @@ -10,7 +10,7 @@ use ContextDev\Core\Contracts\BaseModel; /** - * Detect meaning-level changes to tracked page content, ignoring cosmetic or paraphrase-only differences. Which changes are meaningful is judged against the extract target's `instructions` (and `schema`, when provided). + * Detect meaning-level changes to page content, ignoring cosmetic or instruction-irrelevant differences. Which changes are meaningful is judged against the page or extract target's `instructions` (and an extract target's `schema`, when provided). * * @phpstan-type MonitorsSemanticChangeDetectionShape = array{ * type: 'semantic', confidenceThreshold?: float|null diff --git a/src/Monitors/MonitorUpdateResponse/Target/MonitorsPageTarget.php b/src/Monitors/MonitorUpdateResponse/Target/MonitorsPageTarget.php index 80d0b6b..3fd1467 100644 --- a/src/Monitors/MonitorUpdateResponse/Target/MonitorsPageTarget.php +++ b/src/Monitors/MonitorUpdateResponse/Target/MonitorsPageTarget.php @@ -10,10 +10,13 @@ use ContextDev\Core\Contracts\BaseModel; /** - * Watch a single web page. + * Watch a single web page. Exact detection reports visible-text diffs; semantic detection judges confirmed stable diffs against `instructions`. * * @phpstan-type MonitorsPageTargetShape = array{ - * type: 'page', url: string, normalizeWhitespace?: bool|null + * type: 'page', + * url: string, + * instructions?: string|null, + * normalizeWhitespace?: bool|null, * } */ final class MonitorsPageTarget implements BaseModel @@ -28,6 +31,12 @@ final class MonitorsPageTarget implements BaseModel #[Required] public string $url; + /** + * Plain-language goal describing which page changes matter. When provided without change_detection, semantic detection is inferred. + */ + #[Optional] + public ?string $instructions; + /** * Normalize whitespace before comparing or analyzing text. */ @@ -60,12 +69,14 @@ public function __construct() */ public static function with( string $url, + ?string $instructions = null, ?bool $normalizeWhitespace = null ): self { $self = new self; $self['url'] = $url; + null !== $instructions && $self['instructions'] = $instructions; null !== $normalizeWhitespace && $self['normalizeWhitespace'] = $normalizeWhitespace; return $self; @@ -90,6 +101,17 @@ public function withURL(string $url): self return $self; } + /** + * Plain-language goal describing which page changes matter. When provided without change_detection, semantic detection is inferred. + */ + public function withInstructions(string $instructions): self + { + $self = clone $this; + $self['instructions'] = $instructions; + + return $self; + } + /** * Normalize whitespace before comparing or analyzing text. */ diff --git a/src/ServiceContracts/BatchContract.php b/src/ServiceContracts/BatchContract.php new file mode 100644 index 0000000..dd2416b --- /dev/null +++ b/src/ServiceContracts/BatchContract.php @@ -0,0 +1,106 @@ + $searchType `prefix` for as-you-type prefix matching (default), `exact` for full-token matching + * @param Status|value-of $status filter by status + * @param string $tags comma-separated list of tags to filter by (matches batches having any of them) + * @param RequestOpts|null $requestOptions + * + * @throws APIException + */ + public function list( + ?string $cursor = null, + ?int $limit = null, + ?string $q = null, + SearchType|string|null $searchType = null, + Status|string|null $status = null, + ?string $tags = null, + RequestOptions|array|null $requestOptions = null, + ): BatchListResponse; + + /** + * @api + * + * @param string $batchID ID of the batch to retrieve or cancel + * @param RequestOpts|null $requestOptions + * + * @throws APIException + */ + public function cancel( + string $batchID, + RequestOptions|array|null $requestOptions = null + ): BatchCancelResponse; + + /** + * @api + * + * @param string $batchID ID of the batch to retrieve or cancel + * @param string $cursor next_cursor from the previous page + * @param int $limit Records per page. Defaults to 25. A page can close early so its payload stays under ~8 MB; rely on next_cursor rather than counting records. + * @param RequestOpts|null $requestOptions + * + * @throws APIException + */ + public function getResults( + string $batchID, + ?string $cursor = null, + ?int $limit = null, + RequestOptions|array|null $requestOptions = null, + ): BatchGetResultsResponse; + + /** + * @api + * + * @param Identifiers|IdentifiersShape $identifiers Known identifiers for the person. At least one identifier is required. + * @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 + * + * @throws APIException + */ + public function submit( + Identifiers|array $identifiers, + ?array $tags = null, + ?int $timeoutMs = null, + RequestOptions|array|null $requestOptions = null, + ): BatchSubmitResponse; +} diff --git a/src/ServiceContracts/BatchRawContract.php b/src/ServiceContracts/BatchRawContract.php new file mode 100644 index 0000000..39e7673 --- /dev/null +++ b/src/ServiceContracts/BatchRawContract.php @@ -0,0 +1,100 @@ + + * + * @throws APIException + */ + public function retrieve( + string $batchID, + RequestOptions|array|null $requestOptions = null + ): BaseResponse; + + /** + * @api + * + * @param array|BatchListParams $params + * @param RequestOpts|null $requestOptions + * + * @return BaseResponse + * + * @throws APIException + */ + public function list( + array|BatchListParams $params, + RequestOptions|array|null $requestOptions = null, + ): BaseResponse; + + /** + * @api + * + * @param string $batchID ID of the batch to retrieve or cancel + * @param RequestOpts|null $requestOptions + * + * @return BaseResponse + * + * @throws APIException + */ + public function cancel( + string $batchID, + RequestOptions|array|null $requestOptions = null + ): BaseResponse; + + /** + * @api + * + * @param string $batchID ID of the batch to retrieve or cancel + * @param array|BatchGetResultsParams $params + * @param RequestOpts|null $requestOptions + * + * @return BaseResponse + * + * @throws APIException + */ + public function getResults( + string $batchID, + array|BatchGetResultsParams $params, + RequestOptions|array|null $requestOptions = null, + ): BaseResponse; + + /** + * @api + * + * @param array|BatchSubmitParams $params + * @param RequestOpts|null $requestOptions + * + * @return BaseResponse + * + * @throws APIException + */ + public function submit( + array|BatchSubmitParams $params, + RequestOptions|array|null $requestOptions = null, + ): BaseResponse; +} diff --git a/src/ServiceContracts/MonitorsContract.php b/src/ServiceContracts/MonitorsContract.php index 6a3ae2e..5f9c1fd 100644 --- a/src/ServiceContracts/MonitorsContract.php +++ b/src/ServiceContracts/MonitorsContract.php @@ -34,9 +34,9 @@ use ContextDev\RequestOptions; /** + * @phpstan-import-type TargetShape from \ContextDev\Monitors\MonitorCreateParams\Target * @phpstan-import-type ChangeDetectionShape from \ContextDev\Monitors\MonitorCreateParams\ChangeDetection * @phpstan-import-type ScheduleShape from \ContextDev\Monitors\MonitorCreateParams\Schedule - * @phpstan-import-type TargetShape from \ContextDev\Monitors\MonitorCreateParams\Target * @phpstan-import-type WebhookShape from \ContextDev\Monitors\MonitorCreateParams\Webhook * @phpstan-import-type ChangeDetectionShape from \ContextDev\Monitors\MonitorUpdateParams\ChangeDetection as ChangeDetectionShape1 * @phpstan-import-type ScheduleShape from \ContextDev\Monitors\MonitorUpdateParams\Schedule as ScheduleShape1 @@ -49,10 +49,10 @@ interface MonitorsContract /** * @api * - * @param ChangeDetectionShape $changeDetection discriminated union describing how changes are detected - * @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 ChangeDetectionShape $changeDetection discriminated union describing how changes are detected * @param Mode|value-of $mode Top-level monitor category. Always `web` today; the concrete behavior is described by `target` and `change_detection`. + * @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 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 @@ -60,11 +60,11 @@ interface MonitorsContract * @throws APIException */ public function create( - MonitorsExactChangeDetection|array|MonitorsSemanticChangeDetection $changeDetection, string $name, - Schedule|array $schedule, MonitorsPageTarget|array|MonitorsSitemapTarget|MonitorsExtractTarget $target, + MonitorsExactChangeDetection|array|MonitorsSemanticChangeDetection|null $changeDetection = null, Mode|string|null $mode = null, + Schedule|array|null $schedule = null, ?array $tags = null, Webhook|array|null $webhook = null, RequestOptions|array|null $requestOptions = null, diff --git a/src/Services/BatchRawService.php b/src/Services/BatchRawService.php new file mode 100644 index 0000000..e3aa5f0 --- /dev/null +++ b/src/Services/BatchRawService.php @@ -0,0 +1,195 @@ + + * + * @throws APIException + */ + public function retrieve( + string $batchID, + RequestOptions|array|null $requestOptions = null + ): BaseResponse { + // @phpstan-ignore-next-line return.type + return $this->client->request( + method: 'get', + path: ['batch/%1$s', $batchID], + options: $requestOptions, + convert: BatchGetResponse::class, + ); + } + + /** + * @api + * + * List your batches from newest to oldest. Filter by status or continue with a cursor. + * + * @param array{ + * cursor?: string, + * limit?: int, + * q?: string, + * searchType?: SearchType|value-of, + * status?: Status|value-of, + * tags?: string, + * }|BatchListParams $params + * @param RequestOpts|null $requestOptions + * + * @return BaseResponse + * + * @throws APIException + */ + public function list( + array|BatchListParams $params, + RequestOptions|array|null $requestOptions = null, + ): BaseResponse { + [$parsed, $options] = BatchListParams::parseRequest( + $params, + $requestOptions, + ); + + // @phpstan-ignore-next-line return.type + return $this->client->request( + method: 'get', + path: 'batch/list', + query: Util::array_transform_keys( + $parsed, + ['searchType' => 'search_type'] + ), + options: $options, + convert: BatchListResponse::class, + ); + } + + /** + * @api + * + * Stop a batch from starting new pages. In-progress pages finish, and unused credits are refunded. + * + * @param string $batchID ID of the batch to retrieve or cancel + * @param RequestOpts|null $requestOptions + * + * @return BaseResponse + * + * @throws APIException + */ + public function cancel( + string $batchID, + RequestOptions|array|null $requestOptions = null + ): BaseResponse { + // @phpstan-ignore-next-line return.type + return $this->client->request( + method: 'post', + path: ['batch/%1$s/cancel', $batchID], + options: $requestOptions, + convert: BatchCancelResponse::class, + ); + } + + /** + * @api + * + * Page through the result records of a finished batch as JSON, in the same order as the downloadable result files. Use this instead of downloading and parsing the NDJSON files yourself. + * + * @param string $batchID ID of the batch to retrieve or cancel + * @param array{cursor?: string, limit?: int}|BatchGetResultsParams $params + * @param RequestOpts|null $requestOptions + * + * @return BaseResponse + * + * @throws APIException + */ + public function getResults( + string $batchID, + array|BatchGetResultsParams $params, + RequestOptions|array|null $requestOptions = null, + ): BaseResponse { + [$parsed, $options] = BatchGetResultsParams::parseRequest( + $params, + $requestOptions, + ); + + // @phpstan-ignore-next-line return.type + return $this->client->request( + method: 'get', + path: ['batch/%1$s/results', $batchID], + query: $parsed, + options: $options, + convert: BatchGetResultsResponse::class, + ); + } + + /** + * @api + * + * Retrieve and normalize a person profile from identifiers. + * + * @param array{ + * identifiers: Identifiers|IdentifiersShape, + * tags?: list, + * timeoutMs?: int, + * }|BatchSubmitParams $params + * @param RequestOpts|null $requestOptions + * + * @return BaseResponse + * + * @throws APIException + */ + public function submit( + array|BatchSubmitParams $params, + RequestOptions|array|null $requestOptions = null, + ): BaseResponse { + [$parsed, $options] = BatchSubmitParams::parseRequest( + $params, + $requestOptions, + ); + + // @phpstan-ignore-next-line return.type + return $this->client->request( + method: 'post', + path: 'people/retrieve', + body: (object) $parsed, + options: $options, + convert: BatchSubmitResponse::class, + ); + } +} diff --git a/src/Services/BatchService.php b/src/Services/BatchService.php new file mode 100644 index 0000000..386c228 --- /dev/null +++ b/src/Services/BatchService.php @@ -0,0 +1,178 @@ +raw = new BatchRawService($client); + } + + /** + * @api + * + * Check progress and get download links when the batch finishes. Also returns the rejected-URL list and webhook signing secret from submission, so nothing is lost if the submit response was dropped. + * + * @param string $batchID ID of the batch to retrieve or cancel + * @param RequestOpts|null $requestOptions + * + * @throws APIException + */ + public function retrieve( + string $batchID, + RequestOptions|array|null $requestOptions = null + ): BatchGetResponse { + // @phpstan-ignore-next-line argument.type + $response = $this->raw->retrieve($batchID, requestOptions: $requestOptions); + + return $response->parse(); + } + + /** + * @api + * + * List your batches from newest to oldest. Filter by status or continue with a cursor. + * + * @param string $cursor cursor from the previous page + * @param int $limit Batches per page. Defaults to 25. + * @param string $q free-text search term, matched against the batch id, crawl source (start URL or sitemap domain), and tags + * @param SearchType|value-of $searchType `prefix` for as-you-type prefix matching (default), `exact` for full-token matching + * @param Status|value-of $status filter by status + * @param string $tags comma-separated list of tags to filter by (matches batches having any of them) + * @param RequestOpts|null $requestOptions + * + * @throws APIException + */ + public function list( + ?string $cursor = null, + ?int $limit = null, + ?string $q = null, + SearchType|string|null $searchType = null, + Status|string|null $status = null, + ?string $tags = null, + RequestOptions|array|null $requestOptions = null, + ): BatchListResponse { + $params = Util::removeNulls( + [ + 'cursor' => $cursor, + 'limit' => $limit, + 'q' => $q, + 'searchType' => $searchType, + 'status' => $status, + 'tags' => $tags, + ], + ); + + // @phpstan-ignore-next-line argument.type + $response = $this->raw->list(params: $params, requestOptions: $requestOptions); + + return $response->parse(); + } + + /** + * @api + * + * Stop a batch from starting new pages. In-progress pages finish, and unused credits are refunded. + * + * @param string $batchID ID of the batch to retrieve or cancel + * @param RequestOpts|null $requestOptions + * + * @throws APIException + */ + public function cancel( + string $batchID, + RequestOptions|array|null $requestOptions = null + ): BatchCancelResponse { + // @phpstan-ignore-next-line argument.type + $response = $this->raw->cancel($batchID, requestOptions: $requestOptions); + + return $response->parse(); + } + + /** + * @api + * + * Page through the result records of a finished batch as JSON, in the same order as the downloadable result files. Use this instead of downloading and parsing the NDJSON files yourself. + * + * @param string $batchID ID of the batch to retrieve or cancel + * @param string $cursor next_cursor from the previous page + * @param int $limit Records per page. Defaults to 25. A page can close early so its payload stays under ~8 MB; rely on next_cursor rather than counting records. + * @param RequestOpts|null $requestOptions + * + * @throws APIException + */ + public function getResults( + string $batchID, + ?string $cursor = null, + ?int $limit = null, + RequestOptions|array|null $requestOptions = null, + ): BatchGetResultsResponse { + $params = Util::removeNulls(['cursor' => $cursor, 'limit' => $limit]); + + // @phpstan-ignore-next-line argument.type + $response = $this->raw->getResults($batchID, params: $params, requestOptions: $requestOptions); + + return $response->parse(); + } + + /** + * @api + * + * Retrieve and normalize a person profile from identifiers. + * + * @param Identifiers|IdentifiersShape $identifiers Known identifiers for the person. At least one identifier is required. + * @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 + * + * @throws APIException + */ + public function submit( + Identifiers|array $identifiers, + ?array $tags = null, + ?int $timeoutMs = null, + RequestOptions|array|null $requestOptions = null, + ): BatchSubmitResponse { + $params = Util::removeNulls( + [ + 'identifiers' => $identifiers, + 'tags' => $tags, + 'timeoutMs' => $timeoutMs, + ], + ); + + // @phpstan-ignore-next-line argument.type + $response = $this->raw->submit(params: $params, requestOptions: $requestOptions); + + return $response->parse(); + } +} diff --git a/src/Services/MonitorsRawService.php b/src/Services/MonitorsRawService.php index 365560f..ae9e8ed 100644 --- a/src/Services/MonitorsRawService.php +++ b/src/Services/MonitorsRawService.php @@ -43,9 +43,9 @@ /** * Monitor pages, sitemaps, and extracted website data for exact or semantic changes. Webhook payloads are documented by the MonitorsChangeDetectedWebhookPayload and MonitorsRunCompletedWebhookPayload schemas. * + * @phpstan-import-type TargetShape from \ContextDev\Monitors\MonitorCreateParams\Target * @phpstan-import-type ChangeDetectionShape from \ContextDev\Monitors\MonitorCreateParams\ChangeDetection * @phpstan-import-type ScheduleShape from \ContextDev\Monitors\MonitorCreateParams\Schedule - * @phpstan-import-type TargetShape from \ContextDev\Monitors\MonitorCreateParams\Target * @phpstan-import-type WebhookShape from \ContextDev\Monitors\MonitorCreateParams\Webhook * @phpstan-import-type ChangeDetectionShape from \ContextDev\Monitors\MonitorUpdateParams\ChangeDetection as ChangeDetectionShape1 * @phpstan-import-type ScheduleShape from \ContextDev\Monitors\MonitorUpdateParams\Schedule as ScheduleShape1 @@ -67,11 +67,11 @@ public function __construct(private Client $client) {} * Creates a monitor. The request body is a union of the supported target/change detection combinations. The monitor runs immediately after creation to create its initial baseline. * * @param array{ - * changeDetection: ChangeDetectionShape, * name: string, - * schedule: Schedule|ScheduleShape, * target: TargetShape, + * changeDetection?: ChangeDetectionShape, * mode?: Mode|value-of, + * schedule?: Schedule|ScheduleShape, * tags?: list, * webhook?: Webhook|WebhookShape|null, * }|MonitorCreateParams $params diff --git a/src/Services/MonitorsService.php b/src/Services/MonitorsService.php index 0ed99c1..e8c8926 100644 --- a/src/Services/MonitorsService.php +++ b/src/Services/MonitorsService.php @@ -39,9 +39,9 @@ /** * Monitor pages, sitemaps, and extracted website data for exact or semantic changes. Webhook payloads are documented by the MonitorsChangeDetectedWebhookPayload and MonitorsRunCompletedWebhookPayload schemas. * + * @phpstan-import-type TargetShape from \ContextDev\Monitors\MonitorCreateParams\Target * @phpstan-import-type ChangeDetectionShape from \ContextDev\Monitors\MonitorCreateParams\ChangeDetection * @phpstan-import-type ScheduleShape from \ContextDev\Monitors\MonitorCreateParams\Schedule - * @phpstan-import-type TargetShape from \ContextDev\Monitors\MonitorCreateParams\Target * @phpstan-import-type WebhookShape from \ContextDev\Monitors\MonitorCreateParams\Webhook * @phpstan-import-type ChangeDetectionShape from \ContextDev\Monitors\MonitorUpdateParams\ChangeDetection as ChangeDetectionShape1 * @phpstan-import-type ScheduleShape from \ContextDev\Monitors\MonitorUpdateParams\Schedule as ScheduleShape1 @@ -69,10 +69,10 @@ public function __construct(private Client $client) * * Creates a monitor. The request body is a union of the supported target/change detection combinations. The monitor runs immediately after creation to create its initial baseline. * - * @param ChangeDetectionShape $changeDetection discriminated union describing how changes are detected - * @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 ChangeDetectionShape $changeDetection discriminated union describing how changes are detected * @param Mode|value-of $mode Top-level monitor category. Always `web` today; the concrete behavior is described by `target` and `change_detection`. + * @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 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 @@ -80,22 +80,22 @@ public function __construct(private Client $client) * @throws APIException */ public function create( - MonitorsExactChangeDetection|array|MonitorsSemanticChangeDetection $changeDetection, string $name, - Schedule|array $schedule, MonitorsPageTarget|array|MonitorsSitemapTarget|MonitorsExtractTarget $target, + MonitorsExactChangeDetection|array|MonitorsSemanticChangeDetection|null $changeDetection = null, Mode|string|null $mode = null, + Schedule|array|null $schedule = null, ?array $tags = null, Webhook|array|null $webhook = null, RequestOptions|array|null $requestOptions = null, ): MonitorNewResponse { $params = Util::removeNulls( [ - 'changeDetection' => $changeDetection, 'name' => $name, - 'schedule' => $schedule, 'target' => $target, + 'changeDetection' => $changeDetection, 'mode' => $mode, + 'schedule' => $schedule, 'tags' => $tags, 'webhook' => $webhook, ], diff --git a/src/Version.php b/src/Version.php index 1c11a97..f690bfb 100644 --- a/src/Version.php +++ b/src/Version.php @@ -5,5 +5,5 @@ namespace ContextDev; // x-release-please-start-version -const VERSION = '2.5.0'; +const VERSION = '2.6.0'; // x-release-please-end diff --git a/src/Web/WebWebScrapeHTMLResponse.php b/src/Web/WebWebScrapeHTMLResponse.php index 12aab0e..a1b31a6 100644 --- a/src/Web/WebWebScrapeHTMLResponse.php +++ b/src/Web/WebWebScrapeHTMLResponse.php @@ -8,12 +8,14 @@ use ContextDev\Core\Attributes\Required; use ContextDev\Core\Concerns\SdkModel; use ContextDev\Core\Contracts\BaseModel; +use ContextDev\Web\WebWebScrapeHTMLResponse\ActionsApplied; use ContextDev\Web\WebWebScrapeHTMLResponse\KeyMetadata; use ContextDev\Web\WebWebScrapeHTMLResponse\Metadata; use ContextDev\Web\WebWebScrapeHTMLResponse\Type; /** * @phpstan-import-type MetadataShape from \ContextDev\Web\WebWebScrapeHTMLResponse\Metadata + * @phpstan-import-type ActionsAppliedShape from \ContextDev\Web\WebWebScrapeHTMLResponse\ActionsApplied * @phpstan-import-type KeyMetadataShape from \ContextDev\Web\WebWebScrapeHTMLResponse\KeyMetadata * * @phpstan-type WebWebScrapeHTMLResponseShape = array{ @@ -22,6 +24,8 @@ * success: bool, * type: Type|value-of, * url: string, + * actionsApplied?: list|null, + * actionsHTMLStale?: bool|null, * keyMetadata?: null|KeyMetadata|KeyMetadataShape, * } */ @@ -62,6 +66,20 @@ final class WebWebScrapeHTMLResponse implements BaseModel #[Required] public string $url; + /** + * One verified outcome per requested browser action, in request order. + * + * @var list|null $actionsApplied + */ + #[Optional(list: ActionsApplied::class)] + public ?array $actionsApplied; + + /** + * True when an action was applied but the returned content could not be refreshed afterward. + */ + #[Optional('actionsHtmlStale')] + public ?bool $actionsHTMLStale; + /** * Metadata about the API key used for the request. Included in every response whenever a valid API key is provided, even when the response status is not 200. */ @@ -101,6 +119,7 @@ public function __construct() * * @param Metadata|MetadataShape $metadata * @param Type|value-of $type + * @param list|null $actionsApplied * @param KeyMetadata|KeyMetadataShape|null $keyMetadata */ public static function with( @@ -109,6 +128,8 @@ public static function with( bool $success, Type|string $type, string $url, + ?array $actionsApplied = null, + ?bool $actionsHTMLStale = null, KeyMetadata|array|null $keyMetadata = null, ): self { $self = new self; @@ -119,6 +140,8 @@ public static function with( $self['type'] = $type; $self['url'] = $url; + null !== $actionsApplied && $self['actionsApplied'] = $actionsApplied; + null !== $actionsHTMLStale && $self['actionsHTMLStale'] = $actionsHTMLStale; null !== $keyMetadata && $self['keyMetadata'] = $keyMetadata; return $self; @@ -183,6 +206,30 @@ public function withURL(string $url): self return $self; } + /** + * One verified outcome per requested browser action, in request order. + * + * @param list $actionsApplied + */ + public function withActionsApplied(array $actionsApplied): self + { + $self = clone $this; + $self['actionsApplied'] = $actionsApplied; + + return $self; + } + + /** + * True when an action was applied but the returned content could not be refreshed afterward. + */ + public function withActionsHTMLStale(bool $actionsHTMLStale): self + { + $self = clone $this; + $self['actionsHTMLStale'] = $actionsHTMLStale; + + return $self; + } + /** * Metadata about the API key used for the request. Included in every response whenever a valid API key is provided, even when the response status is not 200. * diff --git a/src/Web/WebWebScrapeHTMLResponse/ActionsApplied.php b/src/Web/WebWebScrapeHTMLResponse/ActionsApplied.php new file mode 100644 index 0000000..fa00ce3 --- /dev/null +++ b/src/Web/WebWebScrapeHTMLResponse/ActionsApplied.php @@ -0,0 +1,170 @@ +, + * completionEvidence?: string|null, + * durationMs?: float|null, + * error?: string|null, + * method?: string|null, + * targetDescription?: string|null, + * } + */ +final class ActionsApplied implements BaseModel +{ + /** @use SdkModel */ + use SdkModel; + + #[Required] + public string $instruction; + + /** + * Applied means the requested page state was visibly verified. Failed means it was not verified. Skipped means it was not attempted. + * + * @var value-of $status + */ + #[Required(enum: Status::class)] + public string $status; + + /** + * Visible page evidence used to verify an applied action. + */ + #[Optional] + public ?string $completionEvidence; + + #[Optional] + public ?float $durationMs; + + #[Optional] + public ?string $error; + + #[Optional] + public ?string $method; + + #[Optional] + public ?string $targetDescription; + + /** + * `new ActionsApplied()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * ActionsApplied::with(instruction: ..., status: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new ActionsApplied)->withInstruction(...)->withStatus(...) + * ``` + */ + public function __construct() + { + $this->initialize(); + } + + /** + * Construct an instance from the required parameters. + * + * You must use named parameters to construct any parameters with a default value. + * + * @param Status|value-of $status + */ + public static function with( + string $instruction, + Status|string $status, + ?string $completionEvidence = null, + ?float $durationMs = null, + ?string $error = null, + ?string $method = null, + ?string $targetDescription = null, + ): self { + $self = new self; + + $self['instruction'] = $instruction; + $self['status'] = $status; + + null !== $completionEvidence && $self['completionEvidence'] = $completionEvidence; + null !== $durationMs && $self['durationMs'] = $durationMs; + null !== $error && $self['error'] = $error; + null !== $method && $self['method'] = $method; + null !== $targetDescription && $self['targetDescription'] = $targetDescription; + + return $self; + } + + public function withInstruction(string $instruction): self + { + $self = clone $this; + $self['instruction'] = $instruction; + + return $self; + } + + /** + * Applied means the requested page state was visibly verified. Failed means it was not verified. Skipped means it was not attempted. + * + * @param Status|value-of $status + */ + public function withStatus(Status|string $status): self + { + $self = clone $this; + $self['status'] = $status; + + return $self; + } + + /** + * Visible page evidence used to verify an applied action. + */ + public function withCompletionEvidence(string $completionEvidence): self + { + $self = clone $this; + $self['completionEvidence'] = $completionEvidence; + + return $self; + } + + public function withDurationMs(float $durationMs): self + { + $self = clone $this; + $self['durationMs'] = $durationMs; + + return $self; + } + + public function withError(string $error): self + { + $self = clone $this; + $self['error'] = $error; + + return $self; + } + + public function withMethod(string $method): self + { + $self = clone $this; + $self['method'] = $method; + + return $self; + } + + public function withTargetDescription(string $targetDescription): self + { + $self = clone $this; + $self['targetDescription'] = $targetDescription; + + return $self; + } +} diff --git a/src/Web/WebWebScrapeHTMLResponse/ActionsApplied/Status.php b/src/Web/WebWebScrapeHTMLResponse/ActionsApplied/Status.php new file mode 100644 index 0000000..354d3ad --- /dev/null +++ b/src/Web/WebWebScrapeHTMLResponse/ActionsApplied/Status.php @@ -0,0 +1,17 @@ +|null, + * actionsHTMLStale?: bool|null, * keyMetadata?: null|KeyMetadata|KeyMetadataShape, * } */ @@ -59,6 +63,20 @@ final class WebWebScrapeMdResponse implements BaseModel #[Required] public string $url; + /** + * One verified outcome per requested browser action, in request order. + * + * @var list|null $actionsApplied + */ + #[Optional(list: ActionsApplied::class)] + public ?array $actionsApplied; + + /** + * True when an action was applied but the returned content could not be refreshed afterward. + */ + #[Optional('actionsHtmlStale')] + public ?bool $actionsHTMLStale; + /** * Metadata about the API key used for the request. Included in every response whenever a valid API key is provided, even when the response status is not 200. */ @@ -97,6 +115,7 @@ public function __construct() * You must use named parameters to construct any parameters with a default value. * * @param Metadata|MetadataShape $metadata + * @param list|null $actionsApplied * @param KeyMetadata|KeyMetadataShape|null $keyMetadata */ public static function with( @@ -105,6 +124,8 @@ public static function with( Metadata|array $metadata, bool $success, string $url, + ?array $actionsApplied = null, + ?bool $actionsHTMLStale = null, KeyMetadata|array|null $keyMetadata = null, ): self { $self = new self; @@ -115,6 +136,8 @@ public static function with( $self['success'] = $success; $self['url'] = $url; + null !== $actionsApplied && $self['actionsApplied'] = $actionsApplied; + null !== $actionsHTMLStale && $self['actionsHTMLStale'] = $actionsHTMLStale; null !== $keyMetadata && $self['keyMetadata'] = $keyMetadata; return $self; @@ -177,6 +200,30 @@ public function withURL(string $url): self return $self; } + /** + * One verified outcome per requested browser action, in request order. + * + * @param list $actionsApplied + */ + public function withActionsApplied(array $actionsApplied): self + { + $self = clone $this; + $self['actionsApplied'] = $actionsApplied; + + return $self; + } + + /** + * True when an action was applied but the returned content could not be refreshed afterward. + */ + public function withActionsHTMLStale(bool $actionsHTMLStale): self + { + $self = clone $this; + $self['actionsHTMLStale'] = $actionsHTMLStale; + + return $self; + } + /** * Metadata about the API key used for the request. Included in every response whenever a valid API key is provided, even when the response status is not 200. * diff --git a/src/Web/WebWebScrapeMdResponse/ActionsApplied.php b/src/Web/WebWebScrapeMdResponse/ActionsApplied.php new file mode 100644 index 0000000..18b886e --- /dev/null +++ b/src/Web/WebWebScrapeMdResponse/ActionsApplied.php @@ -0,0 +1,170 @@ +, + * completionEvidence?: string|null, + * durationMs?: float|null, + * error?: string|null, + * method?: string|null, + * targetDescription?: string|null, + * } + */ +final class ActionsApplied implements BaseModel +{ + /** @use SdkModel */ + use SdkModel; + + #[Required] + public string $instruction; + + /** + * Applied means the requested page state was visibly verified. Failed means it was not verified. Skipped means it was not attempted. + * + * @var value-of $status + */ + #[Required(enum: Status::class)] + public string $status; + + /** + * Visible page evidence used to verify an applied action. + */ + #[Optional] + public ?string $completionEvidence; + + #[Optional] + public ?float $durationMs; + + #[Optional] + public ?string $error; + + #[Optional] + public ?string $method; + + #[Optional] + public ?string $targetDescription; + + /** + * `new ActionsApplied()` is missing required properties by the API. + * + * To enforce required parameters use + * ``` + * ActionsApplied::with(instruction: ..., status: ...) + * ``` + * + * Otherwise ensure the following setters are called + * + * ``` + * (new ActionsApplied)->withInstruction(...)->withStatus(...) + * ``` + */ + public function __construct() + { + $this->initialize(); + } + + /** + * Construct an instance from the required parameters. + * + * You must use named parameters to construct any parameters with a default value. + * + * @param Status|value-of $status + */ + public static function with( + string $instruction, + Status|string $status, + ?string $completionEvidence = null, + ?float $durationMs = null, + ?string $error = null, + ?string $method = null, + ?string $targetDescription = null, + ): self { + $self = new self; + + $self['instruction'] = $instruction; + $self['status'] = $status; + + null !== $completionEvidence && $self['completionEvidence'] = $completionEvidence; + null !== $durationMs && $self['durationMs'] = $durationMs; + null !== $error && $self['error'] = $error; + null !== $method && $self['method'] = $method; + null !== $targetDescription && $self['targetDescription'] = $targetDescription; + + return $self; + } + + public function withInstruction(string $instruction): self + { + $self = clone $this; + $self['instruction'] = $instruction; + + return $self; + } + + /** + * Applied means the requested page state was visibly verified. Failed means it was not verified. Skipped means it was not attempted. + * + * @param Status|value-of $status + */ + public function withStatus(Status|string $status): self + { + $self = clone $this; + $self['status'] = $status; + + return $self; + } + + /** + * Visible page evidence used to verify an applied action. + */ + public function withCompletionEvidence(string $completionEvidence): self + { + $self = clone $this; + $self['completionEvidence'] = $completionEvidence; + + return $self; + } + + public function withDurationMs(float $durationMs): self + { + $self = clone $this; + $self['durationMs'] = $durationMs; + + return $self; + } + + public function withError(string $error): self + { + $self = clone $this; + $self['error'] = $error; + + return $self; + } + + public function withMethod(string $method): self + { + $self = clone $this; + $self['method'] = $method; + + return $self; + } + + public function withTargetDescription(string $targetDescription): self + { + $self = clone $this; + $self['targetDescription'] = $targetDescription; + + return $self; + } +} diff --git a/src/Web/WebWebScrapeMdResponse/ActionsApplied/Status.php b/src/Web/WebWebScrapeMdResponse/ActionsApplied/Status.php new file mode 100644 index 0000000..ad83f5d --- /dev/null +++ b/src/Web/WebWebScrapeMdResponse/ActionsApplied/Status.php @@ -0,0 +1,17 @@ +client = $client; + } + + #[Test] + public function testRetrieve(): void + { + if (UnsupportedMockTests::$skip) { + $this->markTestSkipped('Mock server tests are disabled'); + } + + $result = $this->client->batch->retrieve('batch_9f2c8a'); + + // @phpstan-ignore-next-line method.alreadyNarrowedType + $this->assertInstanceOf(BatchGetResponse::class, $result); + } + + #[Test] + public function testList(): void + { + if (UnsupportedMockTests::$skip) { + $this->markTestSkipped('Mock server tests are disabled'); + } + + $result = $this->client->batch->list(); + + // @phpstan-ignore-next-line method.alreadyNarrowedType + $this->assertInstanceOf(BatchListResponse::class, $result); + } + + #[Test] + public function testCancel(): void + { + if (UnsupportedMockTests::$skip) { + $this->markTestSkipped('Mock server tests are disabled'); + } + + $result = $this->client->batch->cancel('batch_9f2c8a'); + + // @phpstan-ignore-next-line method.alreadyNarrowedType + $this->assertInstanceOf(BatchCancelResponse::class, $result); + } + + #[Test] + public function testGetResults(): void + { + if (UnsupportedMockTests::$skip) { + $this->markTestSkipped('Mock server tests are disabled'); + } + + $result = $this->client->batch->getResults('batch_9f2c8a'); + + // @phpstan-ignore-next-line method.alreadyNarrowedType + $this->assertInstanceOf(BatchGetResultsResponse::class, $result); + } + + #[Test] + public function testSubmit(): void + { + if (UnsupportedMockTests::$skip) { + $this->markTestSkipped('Mock server tests are disabled'); + } + + $result = $this->client->batch->submit(identifiers: []); + + // @phpstan-ignore-next-line method.alreadyNarrowedType + $this->assertInstanceOf(BatchSubmitResponse::class, $result); + } + + #[Test] + public function testSubmitWithOptionalParams(): void + { + if (UnsupportedMockTests::$skip) { + $this->markTestSkipped('Mock server tests are disabled'); + } + + $result = $this->client->batch->submit( + identifiers: [ + 'linkedinURL' => 'https://www.linkedin.com/in/yahia-bakour/', + ], + tags: ['production', 'team-alpha'], + timeoutMs: 1000, + ); + + // @phpstan-ignore-next-line method.alreadyNarrowedType + $this->assertInstanceOf(BatchSubmitResponse::class, $result); + } +} diff --git a/tests/Services/MonitorsTest.php b/tests/Services/MonitorsTest.php index d60e90d..957feec 100644 --- a/tests/Services/MonitorsTest.php +++ b/tests/Services/MonitorsTest.php @@ -48,9 +48,7 @@ public function testCreate(): void } $result = $this->client->monitors->create( - changeDetection: ['type' => 'exact'], name: 'Acme pricing page', - schedule: ['frequency' => 6, 'type' => 'interval', 'unit' => 'hours'], target: ['type' => 'page', 'url' => 'https://acme.com/pricing'], ); @@ -66,15 +64,16 @@ public function testCreateWithOptionalParams(): void } $result = $this->client->monitors->create( - changeDetection: ['type' => 'exact'], name: 'Acme pricing page', - schedule: ['frequency' => 6, 'type' => 'interval', 'unit' => 'hours'], target: [ 'type' => 'page', 'url' => 'https://acme.com/pricing', + 'instructions' => 'Report pricing or plan availability changes. Ignore counters, timestamps, testimonials, and navigation.', 'normalizeWhitespace' => true, ], + changeDetection: ['type' => 'exact'], mode: 'web', + schedule: ['frequency' => 6, 'type' => 'interval', 'unit' => 'hours'], tags: ['pricing', 'competitor'], webhook: [ 'url' => 'https://example.com/webhook',