chore(internal): refactored internal codepaths

Author: stainless-app[bot]

src/Core/BaseClient.php

@@ -4,6 +4,10 @@
 
 namespace CasParser\Core;
 
+use CasParser\Core\Contracts\BasePage;
+use CasParser\Core\Contracts\BaseStream;
+use CasParser\Core\Conversion\Contracts\Converter;
+use CasParser\Core\Conversion\Contracts\ConverterSource;
 use CasParser\Core\Errors\APIStatusError;
 use CasParser\RequestOptions;
 use Http\Discovery\Psr17FactoryDiscovery;
@@ -16,6 +20,15 @@
 use Psr\Http\Message\UriFactoryInterface;
 use Psr\Http\Message\UriInterface;
 
+/**
+ * @phpstan-type normalized_request = array{
+ *   method: string,
+ *   path: string,
+ *   query: array<string, mixed>,
+ *   headers: array<string, string|null|list<string>>,
+ *   body: mixed,
+ * }
+ */
 class BaseClient
 {
     protected UriInterface $baseUrl;
@@ -48,37 +61,56 @@ public function __construct(
      * @param string|list<mixed> $path
      * @param array<string, mixed> $query
      * @param array<string, mixed> $headers
+     * @param class-string<BasePage<mixed>> $page
+     * @param class-string<BaseStream<mixed>> $stream
      */
     public function request(
         string $method,
         string|array $path,
         array $query = [],
         array $headers = [],
         mixed $body = null,
+        string|Converter|ConverterSource|null $convert = null,
+        ?string $page = null,
+        ?string $stream = null,
         mixed $options = [],
     ): mixed {
         // @phpstan-ignore-next-line
-        [$req, $opts] = $this->buildRequest(method: $method, path: $path, query: $query, headers: $headers, opts: $options);
+        [$req, $opts] = $this->buildRequest(method: $method, path: $path, query: $query, headers: $headers, body: $body, opts: $options);
+        ['method' => $method, 'path' => $uri, 'headers' => $headers] = $req;
+
+        $req = $this->requestFactory->createRequest($method, uri: $uri);
+        $req = Util::withSetHeaders($req, headers: $headers);
 
         // @phpstan-ignore-next-line
         $rsp = $this->sendRequest($req, data: $body, opts: $opts, redirectCount: 0, retryCount: 0);
-        if (204 == $rsp->getStatusCode()) {
-            return null; // Handle 204 No Content
+
+        $decoded = Util::decodeContent($rsp);
+
+        if (!is_null($stream)) {
+            return new $stream(
+                convert: $convert,
+                request: $req,
+                response: $rsp,
+                stream: $decoded
+            );
         }
 
-        return Util::decodeContent($rsp);
-    }
+        if (!is_null($page)) {
+            return new $page(
+                convert: $convert,
+                client: $this,
+                request: $req,
+                options: $opts,
+                data: $decoded,
+            );
+        }
 
-    /**
-     * @template Item
-     * @template T of Pagination\AbstractPage<Item>
-     *
-     * @param T $page
-     */
-    public function requestApiList(object $page, RequestOptions $options): ResponseInterface
-    {
-        // @phpstan-ignore-next-line
-        return null;
+        if (!is_null($convert)) {
+            return Conversion::coerce($convert, value: $decoded);
+        }
+
+        return $decoded;
     }
 
     /** @return array<string, string> */
@@ -91,24 +123,25 @@ protected function authHeaders(): array
      * @param string|list<string> $path
      * @param array<string, mixed> $query
      * @param array<string, string|int|list<string|int>|null> $headers
-     * @param array{
+     * @param RequestOptions|array{
      *   timeout?: float|null,
      *   maxRetries?: int|null,
      *   initialRetryDelay?: float|null,
      *   maxRetryDelay?: float|null,
      *   extraHeaders?: list<string>|null,
      *   extraQueryParams?: list<string>|null,
      *   extraBodyParams?: list<string>|null,
-     * }|RequestOptions|null $opts
+     * }|null $opts
      *
-     * @return array{RequestInterface, RequestOptions}
+     * @return array{normalized_request, RequestOptions}
      */
     protected function buildRequest(
         string $method,
         string|array $path,
         array $query,
         array $headers,
-        array|RequestOptions|null $opts,
+        mixed $body,
+        RequestOptions|array|null $opts,
     ): array {
         $opts = [...$this->options->__serialize(), ...RequestOptions::parse($opts)->__serialize()];
         $options = new RequestOptions(...$opts);
@@ -117,16 +150,15 @@ protected function buildRequest(
 
         /** @var array<string, mixed> $mergedQuery */
         $mergedQuery = array_merge_recursive($query, $options->extraQueryParams);
-        $uri = Util::joinUri($this->baseUrl, path: $parsedPath, query: $mergedQuery);
+        $uri = Util::joinUri($this->baseUrl, path: $parsedPath, query: $mergedQuery)->__toString();
 
-        /** @var array<string, string | list<string>> $mergedHeaders */
+        /** @var array<string, string|list<string>|null> $mergedHeaders */
         $mergedHeaders = [...$this->headers,
             ...$this->authHeaders(),
             ...$headers,
             ...$options->extraHeaders, ];
 
-        $req = $this->requestFactory->createRequest(strtoupper($method), uri: $uri);
-        $req = Util::withSetHeaders($req, headers: $mergedHeaders);
+        $req = ['method' => strtoupper($method), 'path' => $uri, 'query' => $mergedQuery, 'headers' => $mergedHeaders, 'body' => $body];
 
         return [$req, $options];
     }

src/Core/Concerns/SdkModel.php

@@ -60,7 +60,7 @@ public function __debugInfo(): array
      */
     public function __toString(): string
     {
-        return json_encode($this->__debugInfo(), flags: JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT) ?: '';
+        return Util::prettyEncodeJson($this->__debugInfo());
     }
 
     /**

src/Core/Contracts/BasePage.php

@@ -4,9 +4,10 @@
 
 namespace CasParser\Core\Contracts;
 
-use CasParser\Core\BaseClient;
-use CasParser\Core\Pagination\PageRequestOptions;
-use Psr\Http\Message\ResponseInterface;
+use CasParser\Client;
+use CasParser\Core\Conversion\Contracts\Converter;
+use CasParser\Core\Conversion\Contracts\ConverterSource;
+use CasParser\RequestOptions;
 
 /**
  * @template Item
@@ -17,12 +18,15 @@ interface BasePage extends \IteratorAggregate
 {
     /**
      * @internal
+     *
+     * @param array<string, mixed> $request
      */
     public function __construct(
-        BaseClient $client,
-        PageRequestOptions $options,
-        ResponseInterface $response,
-        mixed $body,
+        Converter|ConverterSource|string $convert,
+        Client $client,
+        array $request,
+        RequestOptions $options,
+        mixed $data,
     );
 
     public function hasNextPage(): bool;

src/Core/Contracts/BaseStream.php

@@ -4,13 +4,28 @@
 
 namespace CasParser\Core\Contracts;
 
+use CasParser\Core\Conversion\Contracts\Converter;
+use CasParser\Core\Conversion\Contracts\ConverterSource;
+use Psr\Http\Message\RequestInterface;
+use Psr\Http\Message\ResponseInterface;
+
 /**
  * @template TInner
  *
  * @extends \IteratorAggregate<int, TInner>
  */
 interface BaseStream extends \IteratorAggregate
 {
+    /**
+     * @param \Generator<TInner> $stream
+     */
+    public function __construct(
+        Converter|ConverterSource|string $convert,
+        RequestInterface $request,
+        ResponseInterface $response,
+        \Generator $stream,
+    );
+
     /**
      * Manually force the stream to close early.
      * Iterating through will automatically close as well.

src/Core/Errors/APIStatusError.php

@@ -2,9 +2,9 @@
 
 namespace CasParser\Core\Errors;
 
+use CasParser\Core\Util;
 use Psr\Http\Message\RequestInterface;
 use Psr\Http\Message\ResponseInterface;
-use Psr\Http\Message\StreamInterface;
 
 class APIStatusError extends APIError
 {
@@ -23,8 +23,8 @@ public function __construct(
         $this->status = $response->getStatusCode();
 
         $summary = 'Status: '.$this->status.PHP_EOL
-            .'Response Body: '.self::fmtBody($response->getBody()).PHP_EOL
-            .'Request Body: '.self::fmtBody($request->getBody()).PHP_EOL;
+            .'Response Body: '.Util::prettyEncodeJson(Util::decodeJson($response->getBody())).PHP_EOL
+            .'Request Body: '.Util::prettyEncodeJson(Util::decodeJson($request->getBody())).PHP_EOL;
 
         if ('' != $message) {
             $summary .= $message.PHP_EOL.$summary;
@@ -35,7 +35,8 @@ public function __construct(
 
     public static function from(
         RequestInterface $request,
-        ResponseInterface $response
+        ResponseInterface $response,
+        string $message = ''
     ): self {
         $status = $response->getStatusCode();
 
@@ -51,11 +52,6 @@ public static function from(
             default => APIStatusError::class
         };
 
-        return new $cls(request: $request, response: $response);
-    }
-
-    private static function fmtBody(StreamInterface $body): string
-    {
-        return json_encode(json_decode($body->__toString() ?: ''), JSON_PRETTY_PRINT) ?: '';
+        return new $cls(request: $request, response: $response, message: $message);
     }
 }

src/Core/Pagination/AbstractPage.php

@@ -4,25 +4,30 @@
 
 namespace CasParser\Core\Pagination;
 
-use CasParser\Core\BaseClient;
+use CasParser\Client;
 use CasParser\Core\Contracts\BasePage;
+use CasParser\Core\Conversion\Contracts\Converter;
+use CasParser\Core\Conversion\Contracts\ConverterSource;
 use CasParser\Core\Errors\APIStatusError;
-use Psr\Http\Message\ResponseInterface;
+use CasParser\RequestOptions;
 
 /**
  * @internal
  *
  * @template Item
  *
  * @implements BasePage<Item>
+ *
+ * @phpstan-import-type normalized_request from \CasParser\Core\BaseClient
  */
 abstract class AbstractPage implements BasePage
 {
     public function __construct(
-        protected BaseClient $client,
-        protected PageRequestOptions $options,
-        protected ResponseInterface $response,
-        protected mixed $body,
+        protected Converter|ConverterSource|string $convert,
+        protected Client $client,
+        protected array $request,
+        protected RequestOptions $options,
+        protected mixed $data,
     ) {}
 
     /**
@@ -37,7 +42,7 @@ public function hasNextPage(): bool
             return false;
         }
 
-        return null != $this->nextPageRequestOptions();
+        return null != $this->nextRequest();
     }
 
     /**
@@ -51,24 +56,17 @@ public function hasNextPage(): bool
      */
     public function getNextPage(): static
     {
-        $nextOptions = $this->nextPageRequestOptions();
-        if (!$nextOptions) {
+        $next = $this->nextRequest();
+        if (!$next) {
             throw new \RuntimeException(
                 'No next page expected; please check `.hasNextPage()` before calling `.getNextPage()`.'
             );
         }
 
-        $response = $this->client->requestApiList($this, $nextOptions);
-
-        /** @var static of AbstractPage<Item> $nextPage */
-        $nextPage = new static(
-            client: $this->client,
-            options: $nextOptions,
-            response: $response,
-            body: $response->getBody()
-        );
+        [$req, $opts] = $next;
 
-        return $nextPage;
+        // @phpstan-ignore-next-line
+        return $this->client->request(...$req, convert: $this->convert, page: $this, options: $opts);
     }
 
     /**
@@ -102,5 +100,8 @@ public function pagingEachItem(): \Generator
         }
     }
 
-    abstract protected function nextPageRequestOptions(): ?PageRequestOptions;
+    /**
+     * @return array{normalized_request, RequestOptions}
+     */
+    abstract protected function nextRequest(): ?array;
 }