chore: refactor methods

Author: stainless-app[bot]

scripts/lint

@@ -5,4 +5,4 @@ set -e
 cd -- "$(dirname -- "$0")/.."
 
 echo "==> Running PHPStan"
-exec -- ./vendor/bin/phpstan analyse --memory-limit=1G
+exec -- ./vendor/bin/phpstan analyse --memory-limit=2G

src/Client.php

@@ -70,7 +70,7 @@ public function __construct(?string $apiKey = null, ?string $baseUrl = null)
     {
         $this->apiKey = (string) ($apiKey ?? getenv('SCRAPEGRAPHAI_API_KEY'));
 
-        $base = $baseUrl ?? getenv(
+        $baseUrl ??= getenv(
             'SCRAPEGRAPHAI_BASE_URL'
         ) ?: 'https://api.scrapegraphai.com/v1';
 
@@ -85,7 +85,7 @@ public function __construct(?string $apiKey = null, ?string $baseUrl = null)
             headers: [
                 'Content-Type' => 'application/json', 'Accept' => 'application/json',
             ],
-            baseUrl: $base,
+            baseUrl: $baseUrl,
             options: $options,
         );
 

src/Core/BaseClient.php

@@ -29,7 +29,7 @@
  *   body: mixed,
  * }
  */
-class BaseClient
+abstract class BaseClient
 {
     protected UriInterface $baseUrl;
 
@@ -77,14 +77,11 @@ public function request(
         // @phpstan-ignore-next-line
         $rsp = $this->sendRequest($opts, req: $request, data: $body, redirectCount: 0, retryCount: 0);
 
-        $decoded = Util::decodeContent($rsp);
-
         if (!is_null($stream)) {
             return new $stream(
                 convert: $convert,
                 request: $request,
-                response: $rsp,
-                stream: $decoded
+                response: $rsp
             );
         }
 
@@ -93,23 +90,20 @@ public function request(
                 convert: $convert,
                 client: $this,
                 request: $req,
+                response: $rsp,
                 options: $opts,
-                data: $decoded,
             );
         }
 
         if (!is_null($convert)) {
-            return Conversion::coerce($convert, value: $decoded);
+            return Conversion::coerceResponse($convert, response: $rsp);
         }
 
-        return $decoded;
+        return Util::decodeContent($rsp);
     }
 
     /** @return array<string, string> */
-    protected function authHeaders(): array
-    {
-        return [];
-    }
+    abstract protected function authHeaders(): array;
 
     /**
      * @internal

src/Core/Concerns/SdkResponse.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace Scrapegraphai\Core\Concerns;
+
+use Psr\Http\Message\ResponseInterface;
+use Scrapegraphai\Core\Util;
+
+/**
+ * @internal
+ * SdkResponse must only be used in conjunction with classes that use the SdkModel trait
+ */
+trait SdkResponse
+{
+    private ?ResponseInterface $_rawResponse;
+
+    public static function fromResponse(ResponseInterface $response): static
+    {
+        $instance = new static;
+        $instance->_rawResponse = $response;
+        $instance->__unserialize(Util::decodeContent($response)); // @phpstan-ignore-line
+
+        return $instance;
+    }
+
+    public function getRawResponse(): ?ResponseInterface
+    {
+        return $this->_rawResponse;
+    }
+}

src/Core/Contracts/BasePage.php

@@ -4,6 +4,7 @@
 
 namespace Scrapegraphai\Core\Contracts;
 
+use Psr\Http\Message\ResponseInterface;
 use Scrapegraphai\Client;
 use Scrapegraphai\Core\Conversion\Contracts\Converter;
 use Scrapegraphai\Core\Conversion\Contracts\ConverterSource;
@@ -30,7 +31,7 @@ public function __construct(
         Client $client,
         array $request,
         RequestOptions $options,
-        mixed $data,
+        ResponseInterface $response,
     );
 
     public function hasNextPage(): bool;

src/Core/Contracts/BaseStream.php

@@ -18,14 +18,10 @@
  */
 interface BaseStream extends \IteratorAggregate
 {
-    /**
-     * @param \Generator<TInner> $stream
-     */
     public function __construct(
         Converter|ConverterSource|string $convert,
         RequestInterface $request,
         ResponseInterface $response,
-        \Generator $stream,
     );
 
     /**

src/Core/Conversion.php

@@ -4,11 +4,16 @@
 
 namespace Scrapegraphai\Core;
 
+use Psr\Http\Message\ResponseInterface;
 use Scrapegraphai\Core\Conversion\CoerceState;
 use Scrapegraphai\Core\Conversion\Contracts\Converter;
 use Scrapegraphai\Core\Conversion\Contracts\ConverterSource;
+use Scrapegraphai\Core\Conversion\Contracts\ResponseConverter;
 use Scrapegraphai\Core\Conversion\DumpState;
 
+/**
+ * @internal
+ */
 final class Conversion
 {
     public static function dump_unknown(mixed $value, DumpState $state): mixed
@@ -38,6 +43,15 @@ public static function dump_unknown(mixed $value, DumpState $state): mixed
         return $value;
     }
 
+    public static function coerceResponse(Converter|ConverterSource|string $target, ResponseInterface $response): mixed
+    {
+        if (is_a($target, ResponseConverter::class, allow_string: true)) {
+            return $target::fromResponse($response);
+        }
+
+        return self::coerce($target, Util::decodeContent($response));
+    }
+
     public static function coerce(Converter|ConverterSource|string $target, mixed $value, CoerceState $state = new CoerceState): mixed
     {
         if ($value instanceof $target) {

src/Core/Conversion/Contracts/ResponseConverter.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Scrapegraphai\Core\Conversion\Contracts;
+
+use Psr\Http\Message\ResponseInterface;
+
+/**
+ * @internal
+ */
+interface ResponseConverter
+{
+    /**
+     * @internal
+     */
+    public static function fromResponse(ResponseInterface $response): static;
+}

src/Core/Implementation/HasRawResponse.php

@@ -6,7 +6,9 @@
 
 use Scrapegraphai\Core\Attributes\Api;
 use Scrapegraphai\Core\Concerns\SdkModel;
+use Scrapegraphai\Core\Concerns\SdkResponse;
 use Scrapegraphai\Core\Contracts\BaseModel;
+use Scrapegraphai\Core\Conversion\Contracts\ResponseConverter;
 use Scrapegraphai\Crawl\CrawlGetResultsResponse\Result;
 use Scrapegraphai\Crawl\CrawlGetResultsResponse\Status;
 
@@ -17,16 +19,14 @@
  *   taskID?: string,
  *   traceback?: string|null,
  * }
- * When used in a response, this type parameter can define a $rawResponse property.
- * @template TRawResponse of object = object{}
- *
- * @mixin TRawResponse
  */
-final class CrawlGetResultsResponse implements BaseModel
+final class CrawlGetResultsResponse implements BaseModel, ResponseConverter
 {
     /** @use SdkModel<crawl_get_results_response> */
     use SdkModel;
 
+    use SdkResponse;
+
     /**
      * Successful crawl results.
      *
@@ -70,7 +70,7 @@ public static function with(
         $obj = new self;
 
         null !== $result && $obj->result = $result;
-        null !== $status && $obj->status = $status instanceof Status ? $status->value : $status;
+        null !== $status && $obj['status'] = $status;
         null !== $taskID && $obj->taskID = $taskID;
         null !== $traceback && $obj->traceback = $traceback;
 
@@ -96,7 +96,7 @@ public function withResult(mixed $result): self
     public function withStatus(Status|string $status): self
     {
         $obj = clone $this;
-        $obj->status = $status instanceof Status ? $status->value : $status;
+        $obj['status'] = $status;
 
         return $obj;
     }