feat: ensure ->toArray() benefits from structural typing

stainless-app[bot] · stainless-app[bot] · commit 205ab97f9f2b · 2025-08-27T05:12:55.000Z
diff --git a/src/Core/Concerns/SdkModel.php b/src/Core/Concerns/SdkModel.php
@@ -14,6 +14,8 @@
 
 /**
  * @internal
+ *
+ * @template-covariant Data of array<string, mixed>
  */
 trait SdkModel
 {
@@ -65,13 +67,13 @@ public function __toString(): string
     }
 
     /**
+     * @internal
+     *
      * Magic get is intended to occur when we have manually unset
      * a native class property, indicating an omitted value,
-     * or a property overridden with an incongruent type.
+     * or a property overridden with an incongruent type
      *
      * @throws \Exception
-     *
-     * @internal
      */
     public function __get(string $key): mixed
     {
@@ -92,10 +94,12 @@ public function __get(string $key): mixed
         return null;
     }
 
-    /** @return array<string, mixed> */
+    /**
+     * @return Data
+     */
     public function toArray(): array
     {
-        return $this->__serialize();
+        return $this->__serialize(); // @phpstan-ignore-line
     }
 
     /**
@@ -200,8 +204,10 @@ public function jsonSerialize(): array
 
     /**
      * @internal
+     *
+     * @param array<string, mixed> $data
      */
-    public static function fromArray(mixed $data): self
+    public static function fromArray(array $data): self
     {
         return self::converter()->from($data); // @phpstan-ignore-line
     }
diff --git a/src/Core/Concerns/SdkPage.php b/src/Core/Concerns/SdkPage.php
@@ -50,7 +50,7 @@ public function hasNextPage(): bool
      * Before calling this method, you must check if there is a next page
      * using {@link hasNextPage()}.
      *
-     * @return static of AbstractPage<Item>
+     * @return static of static<Item>
      *
      * @throws APIStatusError
      */
diff --git a/src/Core/Contracts/BasePage.php b/src/Core/Contracts/BasePage.php
@@ -33,9 +33,11 @@ public function __construct(
     );
 
     /**
+     * @param array<string, mixed> $data
+     *
      * @return static<Item>
      */
-    public static function fromArray(mixed $data): self;
+    public static function fromArray(array $data): self;
 
     /** @return array<string, mixed> */
     public function toArray(): array;
diff --git a/src/Crawl/CrawlGetResultsResponse.php b/src/Crawl/CrawlGetResultsResponse.php
@@ -10,8 +10,17 @@
 use Scrapegraphai\Crawl\CrawlGetResultsResponse\Result;
 use Scrapegraphai\Crawl\CrawlGetResultsResponse\Status;
 
+/**
+ * @phpstan-type crawl_get_results_response = array{
+ *   result?: mixed|string|null,
+ *   status?: Status::*|null,
+ *   taskID?: string|null,
+ *   traceback?: string|null,
+ * }
+ */
 final class CrawlGetResultsResponse implements BaseModel
 {
+    /** @use SdkModel<crawl_get_results_response> */
     use SdkModel;
 
     /**
diff --git a/src/Crawl/CrawlStartParams.php b/src/Crawl/CrawlStartParams.php
@@ -14,9 +14,22 @@
  * Initiate comprehensive website crawling with sitemap support.
  * Supports both AI extraction mode and markdown conversion mode.
  * Returns a task ID for async processing.
+ *
+ * @phpstan-type crawl_start_params = array{
+ *   url: string,
+ *   depth?: int,
+ *   extractionMode?: bool,
+ *   maxPages?: int,
+ *   prompt?: string|null,
+ *   renderHeavyJs?: bool,
+ *   rules?: Rules,
+ *   schema?: mixed,
+ *   sitemap?: bool,
+ * }
  */
 final class CrawlStartParams implements BaseModel
 {
+    /** @use SdkModel<crawl_start_params> */
     use SdkModel;
     use SdkParams;
 
diff --git a/src/Crawl/CrawlStartParams/Rules.php b/src/Crawl/CrawlStartParams/Rules.php
@@ -8,8 +8,14 @@
 use Scrapegraphai\Core\Concerns\SdkModel;
 use Scrapegraphai\Core\Contracts\BaseModel;
 
+/**
+ * @phpstan-type rules_alias = array{
+ *   exclude?: list<string>|null, sameDomain?: bool|null
+ * }
+ */
 final class Rules implements BaseModel
 {
+    /** @use SdkModel<rules_alias> */
     use SdkModel;
 
     /**
diff --git a/src/Crawl/CrawlStartResponse.php b/src/Crawl/CrawlStartResponse.php
@@ -8,8 +8,12 @@
 use Scrapegraphai\Core\Concerns\SdkModel;
 use Scrapegraphai\Core\Contracts\BaseModel;
 
+/**
+ * @phpstan-type crawl_start_response = array{taskID?: string|null}
+ */
 final class CrawlStartResponse implements BaseModel
 {
+    /** @use SdkModel<crawl_start_response> */
     use SdkModel;
 
     /**
diff --git a/src/Credits/CreditGetResponse.php b/src/Credits/CreditGetResponse.php
@@ -8,8 +8,14 @@
 use Scrapegraphai\Core\Concerns\SdkModel;
 use Scrapegraphai\Core\Contracts\BaseModel;
 
+/**
+ * @phpstan-type credit_get_response = array{
+ *   remainingCredits?: int|null, totalCreditsUsed?: int|null
+ * }
+ */
 final class CreditGetResponse implements BaseModel
 {
+    /** @use SdkModel<credit_get_response> */
     use SdkModel;
 
     /**
diff --git a/src/Feedback/FeedbackSubmitParams.php b/src/Feedback/FeedbackSubmitParams.php
@@ -11,9 +11,14 @@
 
 /**
  * Submit feedback for a specific request.
+ *
+ * @phpstan-type feedback_submit_params = array{
+ *   rating: int, requestID: string, feedbackText?: string|null
+ * }
  */
 final class FeedbackSubmitParams implements BaseModel
 {
+    /** @use SdkModel<feedback_submit_params> */
     use SdkModel;
     use SdkParams;
 
diff --git a/src/Feedback/FeedbackSubmitResponse.php b/src/Feedback/FeedbackSubmitResponse.php
@@ -8,8 +8,17 @@
 use Scrapegraphai\Core\Concerns\SdkModel;
 use Scrapegraphai\Core\Contracts\BaseModel;
 
+/**
+ * @phpstan-type feedback_submit_response = array{
+ *   feedbackID?: string|null,
+ *   feedbackTimestamp?: \DateTimeInterface|null,
+ *   message?: string|null,
+ *   requestID?: string|null,
+ * }
+ */
 final class FeedbackSubmitResponse implements BaseModel
 {
+    /** @use SdkModel<feedback_submit_response> */
     use SdkModel;
 
     #[Api('feedback_id', optional: true)]
diff --git a/src/GenerateSchema/GenerateSchemaCreateParams.php b/src/GenerateSchema/GenerateSchemaCreateParams.php
@@ -12,9 +12,14 @@
 /**
  * Generate or modify JSON schemas based on natural language descriptions.
  * Can create new schemas or extend existing ones.
+ *
+ * @phpstan-type generate_schema_create_params = array{
+ *   userPrompt: string, existingSchema?: mixed
+ * }
  */
 final class GenerateSchemaCreateParams implements BaseModel
 {
+    /** @use SdkModel<generate_schema_create_params> */
     use SdkModel;
     use SdkParams;
 
diff --git a/src/GenerateSchema/GenerateSchemaGetResponse/CompletedSchemaGenerationResponse.php b/src/GenerateSchema/GenerateSchemaGetResponse/CompletedSchemaGenerationResponse.php
@@ -9,8 +9,19 @@
 use Scrapegraphai\Core\Contracts\BaseModel;
 use Scrapegraphai\GenerateSchema\GenerateSchemaGetResponse\CompletedSchemaGenerationResponse\Status;
 
+/**
+ * @phpstan-type completed_schema_generation_response = array{
+ *   error?: string|null,
+ *   generatedSchema?: mixed,
+ *   refinedPrompt?: string|null,
+ *   requestID?: string|null,
+ *   status?: Status::*|null,
+ *   userPrompt?: string|null,
+ * }
+ */
 final class CompletedSchemaGenerationResponse implements BaseModel
 {
+    /** @use SdkModel<completed_schema_generation_response> */
     use SdkModel;
 
     #[Api(nullable: true, optional: true)]
diff --git a/src/GenerateSchema/GenerateSchemaGetResponse/FailedSchemaGenerationResponse.php b/src/GenerateSchema/GenerateSchemaGetResponse/FailedSchemaGenerationResponse.php
@@ -9,8 +9,19 @@
 use Scrapegraphai\Core\Contracts\BaseModel;
 use Scrapegraphai\GenerateSchema\GenerateSchemaGetResponse\FailedSchemaGenerationResponse\Status;
 
+/**
+ * @phpstan-type failed_schema_generation_response = array{
+ *   error?: string|null,
+ *   generatedSchema?: mixed,
+ *   refinedPrompt?: string|null,
+ *   requestID?: string|null,
+ *   status?: Status::*|null,
+ *   userPrompt?: string|null,
+ * }
+ */
 final class FailedSchemaGenerationResponse implements BaseModel
 {
+    /** @use SdkModel<failed_schema_generation_response> */
     use SdkModel;
 
     #[Api(optional: true)]
diff --git a/src/GenerateSchema/GenerateSchemaNewResponse.php b/src/GenerateSchema/GenerateSchemaNewResponse.php
@@ -9,8 +9,19 @@
 use Scrapegraphai\Core\Contracts\BaseModel;
 use Scrapegraphai\GenerateSchema\GenerateSchemaNewResponse\Status;
 
+/**
+ * @phpstan-type generate_schema_new_response = array{
+ *   error?: string|null,
+ *   generatedSchema?: mixed,
+ *   refinedPrompt?: string|null,
+ *   requestID?: string|null,
+ *   status?: Status::*|null,
+ *   userPrompt?: string|null,
+ * }
+ */
 final class GenerateSchemaNewResponse implements BaseModel
 {
+    /** @use SdkModel<generate_schema_new_response> */
     use SdkModel;
 
     #[Api(nullable: true, optional: true)]
diff --git a/src/Healthz/HealthzCheckResponse.php b/src/Healthz/HealthzCheckResponse.php
@@ -8,8 +8,14 @@
 use Scrapegraphai\Core\Concerns\SdkModel;
 use Scrapegraphai\Core\Contracts\BaseModel;
 
+/**
+ * @phpstan-type healthz_check_response = array{
+ *   services?: array<string, string>|null, status?: string|null
+ * }
+ */
 final class HealthzCheckResponse implements BaseModel
 {
+    /** @use SdkModel<healthz_check_response> */
     use SdkModel;
 
     /** @var array<string, string>|null $services */
diff --git a/src/Markdownify/CompletedMarkdownify.php b/src/Markdownify/CompletedMarkdownify.php
@@ -9,8 +9,18 @@
 use Scrapegraphai\Core\Contracts\BaseModel;
 use Scrapegraphai\Markdownify\CompletedMarkdownify\Status;
 
+/**
+ * @phpstan-type completed_markdownify = array{
+ *   error?: string|null,
+ *   requestID?: string|null,
+ *   result?: string|null,
+ *   status?: Status::*|null,
+ *   websiteURL?: string|null,
+ * }
+ */
 final class CompletedMarkdownify implements BaseModel
 {
+    /** @use SdkModel<completed_markdownify> */
     use SdkModel;
 
     #[Api(optional: true)]
diff --git a/src/Markdownify/MarkdownifyConvertParams.php b/src/Markdownify/MarkdownifyConvertParams.php
@@ -11,9 +11,14 @@
 
 /**
  * Convert web page content to clean Markdown format.
+ *
+ * @phpstan-type markdownify_convert_params = array{
+ *   websiteURL: string, headers?: array<string, string>, steps?: list<string>
+ * }
  */
 final class MarkdownifyConvertParams implements BaseModel
 {
+    /** @use SdkModel<markdownify_convert_params> */
     use SdkModel;
     use SdkParams;
 
diff --git a/src/Markdownify/MarkdownifyGetStatusResponse/FailedMarkdownifyResponse.php b/src/Markdownify/MarkdownifyGetStatusResponse/FailedMarkdownifyResponse.php
@@ -9,8 +9,18 @@
 use Scrapegraphai\Core\Contracts\BaseModel;
 use Scrapegraphai\Markdownify\MarkdownifyGetStatusResponse\FailedMarkdownifyResponse\Status;
 
+/**
+ * @phpstan-type failed_markdownify_response = array{
+ *   error?: string|null,
+ *   requestID?: string|null,
+ *   result?: string|null,
+ *   status?: Status::*|null,
+ *   websiteURL?: string|null,
+ * }
+ */
 final class FailedMarkdownifyResponse implements BaseModel
 {
+    /** @use SdkModel<failed_markdownify_response> */
     use SdkModel;
 
     #[Api(optional: true)]
diff --git a/src/Searchscraper/CompletedSearchScraper.php b/src/Searchscraper/CompletedSearchScraper.php
@@ -9,8 +9,20 @@
 use Scrapegraphai\Core\Contracts\BaseModel;
 use Scrapegraphai\Searchscraper\CompletedSearchScraper\Status;
 
+/**
+ * @phpstan-type completed_search_scraper = array{
+ *   error?: string|null,
+ *   numResults?: int|null,
+ *   referenceURLs?: list<string>|null,
+ *   requestID?: string|null,
+ *   result?: mixed,
+ *   status?: Status::*|null,
+ *   userPrompt?: string|null,
+ * }
+ */
 final class CompletedSearchScraper implements BaseModel
 {
+    /** @use SdkModel<completed_search_scraper> */
     use SdkModel;
 
     #[Api(nullable: true, optional: true)]
diff --git a/src/Searchscraper/SearchscraperCreateParams.php b/src/Searchscraper/SearchscraperCreateParams.php
@@ -12,9 +12,17 @@
 /**
  * Performs web search, selects relevant URLs, and extracts structured data from multiple websites.
  * Uses LLM to refine search queries and merge results from different sources.
+ *
+ * @phpstan-type searchscraper_create_params = array{
+ *   userPrompt: string,
+ *   headers?: array<string, string>,
+ *   numResults?: int,
+ *   outputSchema?: mixed,
+ * }
  */
 final class SearchscraperCreateParams implements BaseModel
 {
+    /** @use SdkModel<searchscraper_create_params> */
     use SdkModel;
     use SdkParams;
 
diff --git a/src/Searchscraper/SearchscraperGetStatusResponse/FailedSearchScraperResponse.php b/src/Searchscraper/SearchscraperGetStatusResponse/FailedSearchScraperResponse.php
@@ -9,8 +9,20 @@
 use Scrapegraphai\Core\Contracts\BaseModel;
 use Scrapegraphai\Searchscraper\SearchscraperGetStatusResponse\FailedSearchScraperResponse\Status;
 
+/**
+ * @phpstan-type failed_search_scraper_response = array{
+ *   error?: string|null,
+ *   numResults?: int|null,
+ *   referenceURLs?: list<string>|null,
+ *   requestID?: string|null,
+ *   result?: mixed,
+ *   status?: Status::*|null,
+ *   userPrompt?: string|null,
+ * }
+ */
 final class FailedSearchScraperResponse implements BaseModel
 {
+    /** @use SdkModel<failed_search_scraper_response> */
     use SdkModel;
 
     #[Api(optional: true)]
diff --git a/src/Smartscraper/CompletedSmartscraper.php b/src/Smartscraper/CompletedSmartscraper.php
diff --git a/src/Smartscraper/FailedSmartscraper.php b/src/Smartscraper/FailedSmartscraper.php
diff --git a/src/Smartscraper/SmartscraperCreateParams.php b/src/Smartscraper/SmartscraperCreateParams.php
diff --git a/src/Validate/ValidateAPIKeyResponse.php b/src/Validate/ValidateAPIKeyResponse.php
diff --git a/tests/Core/TestModel.php b/tests/Core/TestModel.php

Original file line number	Diff line number	Diff line change
`@@ -14,6 +14,8 @@`
`14`	`14`
`15`	`15`	`/**`
`16`	`16`	`* @internal`
	`17`	`+ *`
	`18`	`+ * @template-covariant Data of array<string, mixed>`
`17`	`19`	`*/`
`18`	`20`	`trait SdkModel`
`19`	`21`	`{`
`@@ -65,13 +67,13 @@ public function __toString(): string`
`65`	`67`	`}`
`66`	`68`
`67`	`69`	`/**`
	`70`	`+ * @internal`
	`71`	`+ *`
`68`	`72`	`* Magic get is intended to occur when we have manually unset`
`69`	`73`	`* a native class property, indicating an omitted value,`
`70`		`- * or a property overridden with an incongruent type.`
	`74`	`+ * or a property overridden with an incongruent type`
`71`	`75`	`*`
`72`	`76`	`* @throws \Exception`
`73`		`- *`
`74`		`- * @internal`
`75`	`77`	`*/`
`76`	`78`	`public function __get(string $key): mixed`
`77`	`79`	`{`
`@@ -92,10 +94,12 @@ public function __get(string $key): mixed`
`92`	`94`	`return null;`
`93`	`95`	`}`
`94`	`96`
`95`		`- /** @return array<string, mixed> */`
	`97`	`+ /**`
	`98`	`+ * @return Data`
	`99`	`+ */`
`96`	`100`	`public function toArray(): array`
`97`	`101`	`{`
`98`		`- return $this->__serialize();`
	`102`	`+ return $this->__serialize(); // @phpstan-ignore-line`
`99`	`103`	`}`
`100`	`104`
`101`	`105`	`/**`
`@@ -200,8 +204,10 @@ public function jsonSerialize(): array`
`200`	`204`
`201`	`205`	`/**`
`202`	`206`	`* @internal`
	`207`	`+ *`
	`208`	`+ * @param array<string, mixed> $data`
`203`	`209`	`*/`
`204`		`- public static function fromArray(mixed $data): self`
	`210`	`+ public static function fromArray(array $data): self`
`205`	`211`	`{`
`206`	`212`	`return self::converter()->from($data); // @phpstan-ignore-line`
`207`	`213`	`}`
Original file line number	Diff line number	Diff line change
`@@ -50,7 +50,7 @@ public function hasNextPage(): bool`
`50`	`50`	`* Before calling this method, you must check if there is a next page`
`51`	`51`	`* using {@link hasNextPage()}.`
`52`	`52`	`*`
`53`		`- * @return static of AbstractPage<Item>`
	`53`	`+ * @return static of static<Item>`
`54`	`54`	`*`
`55`	`55`	`* @throws APIStatusError`
`56`	`56`	`*/`