WIP

rector.php

@@ -15,6 +15,7 @@
 
     $rectorConfig->skip([
         __DIR__.'/src/Contracts/ResponseContract.php',
+        __DIR__.'/src/Contracts/ResponseMetaContract.php',
         __DIR__.'/src/Testing/ClientFake.php' => FinalizeClassesWithoutChildrenRector::class,
     ]);
 

src/Contracts/ResponseContract.php

@@ -5,6 +5,7 @@
 namespace OpenAI\Contracts;
 
 use ArrayAccess;
+use OpenAI\Responses\ResponseMetaInformation;
 
 /**
  * @template TArray of array
@@ -49,4 +50,6 @@ public function offsetSet(mixed $offset, mixed $value): never;
      * @param  TOffsetKey  $offset
      */
     public function offsetUnset(mixed $offset): never;
+
+//    public function meta(): ResponseMetaInformation;
 }

src/Contracts/ResponseMetaContract.php

@@ -0,0 +1,52 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenAI\Contracts;
+
+use ArrayAccess;
+
+/**
+ * @template TArray of array
+ *
+ * @extends ArrayAccess<key-of<TArray>, value-of<TArray>>
+ *
+ * @internal
+ */
+interface ResponseMetaContract extends ArrayAccess
+{
+    /**
+     * Returns the array representation of the meta information.
+     *
+     * @return TArray
+     */
+    public function toArray(): array;
+
+    /**
+     * @param  key-of<TArray>  $offset
+     */
+    public function offsetExists(mixed $offset): bool;
+
+    /**
+     * @template TOffsetKey of key-of<TArray>
+     *
+     * @param  TOffsetKey  $offset
+     * @return TArray[TOffsetKey]
+     */
+    public function offsetGet(mixed $offset): mixed;
+
+    /**
+     * @template TOffsetKey of key-of<TArray>
+     *
+     * @param  TOffsetKey  $offset
+     * @param  TArray[TOffsetKey] $value
+     */
+    public function offsetSet(mixed $offset, mixed $value): never;
+
+    /**
+     * @template TOffsetKey of key-of<TArray>
+     *
+     * @param  TOffsetKey  $offset
+     */
+    public function offsetUnset(mixed $offset): never;
+}

src/Contracts/TransporterContract.php

@@ -8,6 +8,7 @@
 use OpenAI\Exceptions\TransporterException;
 use OpenAI\Exceptions\UnserializableResponse;
 use OpenAI\ValueObjects\Transporter\Payload;
+use OpenAI\ValueObjects\Transporter\Response;
 use Psr\Http\Message\ResponseInterface;
 
 /**
@@ -17,12 +18,12 @@ interface TransporterContract
 {
     /**
      * Sends a request to a server.
-     **
-     * @return array<array-key, mixed>
+     *
+     * @return Response<array<array-key, mixed>|string>
      *
      * @throws ErrorException|UnserializableResponse|TransporterException
      */
-    public function requestObject(Payload $payload): array|string;
+    public function requestObject(Payload $payload): Response;
 
     /**
      * Sends a content request to a server.

src/Resources/Audio.php

@@ -25,9 +25,9 @@ public function transcribe(array $parameters): TranscriptionResponse
         $payload = Payload::upload('audio/transcriptions', $parameters);
 
         /** @var array{task: ?string, language: ?string, duration: ?float, segments: array<int, array{id: int, seek: int, start: float, end: float, text: string, tokens: array<int, int>, temperature: float, avg_logprob: float, compression_ratio: float, no_speech_prob: float, transient: bool}>, text: string}|string $result */
-        $result = $this->transporter->requestObject($payload);
+        $response = $this->transporter->requestObject($payload);
 
-        return TranscriptionResponse::from($result);
+        return TranscriptionResponse::from($response->data(), $response->meta());
     }
 
     /**

src/Resources/Completions.php

@@ -9,6 +9,7 @@
 use OpenAI\Responses\Completions\CreateStreamedResponse;
 use OpenAI\Responses\StreamResponse;
 use OpenAI\ValueObjects\Transporter\Payload;
+use OpenAI\ValueObjects\Transporter\Response;
 
 final class Completions implements CompletionsContract
 {
@@ -28,10 +29,10 @@ public function create(array $parameters): CreateResponse
 
         $payload = Payload::create('completions', $parameters);
 
-        /** @var array{id: string, object: string, created: int, model: string, choices: array<int, array{text: string, index: int, logprobs: array{tokens: array<int, string>, token_logprobs: array<int, float>, top_logprobs: array<int, string>|null, text_offset: array<int, int>}|null, finish_reason: string}>, usage: array{prompt_tokens: int, completion_tokens: int, total_tokens: int}} $result */
-        $result = $this->transporter->requestObject($payload);
+        /** @var Response<array{id: string, object: string, created: int, model: string, choices: array<int, array{text: string, index: int, logprobs: array{tokens: array<int, string>, token_logprobs: array<int, float>, top_logprobs: array<int, string>|null, text_offset: array<int, int>}|null, finish_reason: string}>, usage: array{prompt_tokens: int, completion_tokens: int, total_tokens: int}}> $response */
+        $response = $this->transporter->requestObject($payload);
 
-        return CreateResponse::from($result);
+        return CreateResponse::from($response->data(), $response->meta());
     }
 
     /**

src/Resources/Files.php

@@ -25,9 +25,9 @@ public function list(): ListResponse
         $payload = Payload::list('files');
 
         /** @var array{object: string, data: array<int, array{id: string, object: string, created_at: int, bytes: int, filename: string, purpose: string, status: string, status_details: array<array-key, mixed>|string|null}>} $result */
-        $result = $this->transporter->requestObject($payload);
+        $response = $this->transporter->requestObject($payload);
 
-        return ListResponse::from($result);
+        return ListResponse::from($response->data(), $response->meta());
     }
 
     /**
@@ -83,9 +83,9 @@ public function delete(string $file): DeleteResponse
     {
         $payload = Payload::delete('files', $file);
 
-        /** @var array{id: string, object: string, deleted: bool} $result */
-        $result = $this->transporter->requestObject($payload);
+        /** @var array{id: string, object: string, deleted: bool} $response */
+        $response = $this->transporter->requestObject($payload);
 
-        return DeleteResponse::from($result);
+        return DeleteResponse::from($response->data(), $response->meta());
     }
 }

src/Resources/Images.php

@@ -25,10 +25,10 @@ public function create(array $parameters): CreateResponse
     {
         $payload = Payload::create('images/generations', $parameters);
 
-        /** @var array{created: int, data: array<int, array{url?: string, b64_json?: string}>} $result */
-        $result = $this->transporter->requestObject($payload);
+        /** @var array{created: int, data: array<int, array{url?: string, b64_json?: string}>} $response */
+        $response = $this->transporter->requestObject($payload);
 
-        return CreateResponse::from($result);
+        return CreateResponse::from($response->data(), $response->meta());
     }
 
     /**
@@ -42,10 +42,10 @@ public function edit(array $parameters): EditResponse
     {
         $payload = Payload::upload('images/edits', $parameters);
 
-        /** @var array{created: int, data: array<int, array{url?: string, b64_json?: string}>} $result */
-        $result = $this->transporter->requestObject($payload);
+        /** @var array{created: int, data: array<int, array{url?: string, b64_json?: string}>} $response */
+        $response = $this->transporter->requestObject($payload);
 
-        return EditResponse::from($result);
+        return EditResponse::from($response->data(), $response->meta());
     }
 
     /**
@@ -59,9 +59,9 @@ public function variation(array $parameters): VariationResponse
     {
         $payload = Payload::upload('images/variations', $parameters);
 
-        /** @var array{created: int, data: array<int, array{url?: string, b64_json?: string}>} $result */
-        $result = $this->transporter->requestObject($payload);
+        /** @var array{created: int, data: array<int, array{url?: string, b64_json?: string}>} $response */
+        $response = $this->transporter->requestObject($payload);
 
-        return VariationResponse::from($result);
+        return VariationResponse::from($response->data(), $response->meta());
     }
 }

src/Resources/Models.php

@@ -23,10 +23,10 @@ public function list(): ListResponse
     {
         $payload = Payload::list('models');
 
-        /** @var array{object: string, data: array<int, array{id: string, object: string, created: int, owned_by: string, permission: array<int, array{id: string, object: string, created: int, allow_create_engine: bool, allow_sampling: bool, allow_logprobs: bool, allow_search_indices: bool, allow_view: bool, allow_fine_tuning: bool, organization: string, group: ?string, is_blocking: bool}>, root: string, parent: ?string}>} $result */
-        $result = $this->transporter->requestObject($payload);
+        /** @var array{object: string, data: array<int, array{id: string, object: string, created: int, owned_by: string, permission: array<int, array{id: string, object: string, created: int, allow_create_engine: bool, allow_sampling: bool, allow_logprobs: bool, allow_search_indices: bool, allow_view: bool, allow_fine_tuning: bool, organization: string, group: ?string, is_blocking: bool}>, root: string, parent: ?string}>} $response */
+        $response = $this->transporter->requestObject($payload);
 
-        return ListResponse::from($result);
+        return ListResponse::from($response->data(), $response->meta());
     }
 
     /**
@@ -38,10 +38,10 @@ public function retrieve(string $model): RetrieveResponse
     {
         $payload = Payload::retrieve('models', $model);
 
-        /** @var array{id: string, object: string, created: int, owned_by: string, permission: array<int, array{id: string, object: string, created: int, allow_create_engine: bool, allow_sampling: bool, allow_logprobs: bool, allow_search_indices: bool, allow_view: bool, allow_fine_tuning: bool, organization: string, group: ?string, is_blocking: bool}>, root: string, parent: ?string} $result */
-        $result = $this->transporter->requestObject($payload);
+        /** @var array{id: string, object: string, created: int, owned_by: string, permission: array<int, array{id: string, object: string, created: int, allow_create_engine: bool, allow_sampling: bool, allow_logprobs: bool, allow_search_indices: bool, allow_view: bool, allow_fine_tuning: bool, organization: string, group: ?string, is_blocking: bool}>, root: string, parent: ?string} $response */
+        $response = $this->transporter->requestObject($payload);
 
-        return RetrieveResponse::from($result);
+        return RetrieveResponse::from($response->data(), $response->meta());
     }
 
     /**
@@ -53,9 +53,9 @@ public function delete(string $model): DeleteResponse
     {
         $payload = Payload::delete('models', $model);
 
-        /** @var array{id: string, object: string, deleted: bool} $result */
-        $result = $this->transporter->requestObject($payload);
+        /** @var array{id: string, object: string, deleted: bool} $response */
+        $response = $this->transporter->requestObject($payload);
 
-        return DeleteResponse::from($result);
+        return DeleteResponse::from($response->data(), $response->meta());
     }
 }

src/Resources/Moderations.php

@@ -23,9 +23,9 @@ public function create(array $parameters): CreateResponse
     {
         $payload = Payload::create('moderations', $parameters);
 
-        /** @var array{id: string, model: string, results: array<int, array{categories: array<string, bool>, category_scores: array<string, float>, flagged: bool}>} $result */
-        $result = $this->transporter->requestObject($payload);
+        /** @var array{id: string, model: string, results: array<int, array{categories: array<string, bool>, category_scores: array<string, float>, flagged: bool}>} $response */
+        $response = $this->transporter->requestObject($payload);
 
-        return CreateResponse::from($result);
+        return CreateResponse::from($response->data(), $response->meta());
     }
 }

src/Responses/Audio/TranscriptionResponse.php

@@ -6,6 +6,7 @@
 
 use OpenAI\Contracts\ResponseContract;
 use OpenAI\Responses\Concerns\ArrayAccessible;
+use OpenAI\Responses\ResponseMetaInformation;
 use OpenAI\Testing\Responses\Concerns\Fakeable;
 
 /**
@@ -29,6 +30,7 @@ private function __construct(
         public readonly ?float $duration,
         public readonly array $segments,
         public readonly string $text,
+        private readonly ResponseMetaInformation $meta,
     ) {
     }
 
@@ -37,7 +39,7 @@ private function __construct(
      *
      * @param  array{task: ?string, language: ?string, duration: ?float, segments: array<int, array{id: int, seek: int, start: float, end: float, text: string, tokens: array<int, int>, temperature: float, avg_logprob: float, compression_ratio: float, no_speech_prob: float, transient: bool}>, text: string}|string  $attributes
      */
-    public static function from(array|string $attributes): self
+    public static function from(array|string $attributes, ResponseMetaInformation $meta): self
     {
         if (is_string($attributes)) {
             $attributes = ['text' => $attributes];
@@ -53,6 +55,7 @@ public static function from(array|string $attributes): self
             $attributes['duration'] ?? null,
             $segments,
             $attributes['text'],
+            $meta,
         );
     }
 
@@ -72,4 +75,9 @@ public function toArray(): array
             'text' => $this->text,
         ];
     }
+
+    public function meta(): ResponseMetaInformation
+    {
+        return $this->meta;
+    }
 }

src/Responses/Completions/CreateResponse.php

@@ -6,6 +6,7 @@
 
 use OpenAI\Contracts\ResponseContract;
 use OpenAI\Responses\Concerns\ArrayAccessible;
+use OpenAI\Responses\ResponseMetaInformation;
 use OpenAI\Testing\Responses\Concerns\Fakeable;
 
 /**
@@ -30,6 +31,7 @@ private function __construct(
         public readonly string $model,
         public readonly array $choices,
         public readonly CreateResponseUsage $usage,
+        private readonly ResponseMetaInformation $meta,
     ) {
     }
 
@@ -38,7 +40,7 @@ private function __construct(
      *
      * @param  array{id: string, object: string, created: int, model: string, choices: array<int, array{text: string, index: int, logprobs: array{tokens: array<int, string>, token_logprobs: array<int, float>, top_logprobs: array<int, string>|null, text_offset: array<int, int>}|null, finish_reason: string}>, usage: array{prompt_tokens: int, completion_tokens: int|null, total_tokens: int}}  $attributes
      */
-    public static function from(array $attributes): self
+    public static function from(array $attributes, ResponseMetaInformation $meta): self
     {
         $choices = array_map(fn (array $result): CreateResponseChoice => CreateResponseChoice::from(
             $result
@@ -51,6 +53,7 @@ public static function from(array $attributes): self
             $attributes['model'],
             $choices,
             CreateResponseUsage::from($attributes['usage']),
+            $meta,
         );
     }
 
@@ -71,4 +74,9 @@ public function toArray(): array
             'usage' => $this->usage->toArray(),
         ];
     }
+
+    public function meta(): ResponseMetaInformation
+    {
+        return $this->meta;
+    }
 }

src/Responses/Files/DeleteResponse.php

@@ -6,6 +6,7 @@
 
 use OpenAI\Contracts\ResponseContract;
 use OpenAI\Responses\Concerns\ArrayAccessible;
+use OpenAI\Responses\ResponseMetaInformation;
 use OpenAI\Testing\Responses\Concerns\Fakeable;
 
 /**
@@ -24,6 +25,7 @@ private function __construct(
         public readonly string $id,
         public readonly string $object,
         public readonly bool $deleted,
+        public readonly ResponseMetaInformation $meta,
     ) {
     }
 
@@ -32,12 +34,13 @@ private function __construct(
      *
      * @param  array{id: string, object: string, deleted: bool}  $attributes
      */
-    public static function from(array $attributes): self
+    public static function from(array $attributes, ResponseMetaInformation $meta): self
     {
         return new self(
             $attributes['id'],
             $attributes['object'],
             $attributes['deleted'],
+            $meta,
         );
     }
 
@@ -52,4 +55,9 @@ public function toArray(): array
             'deleted' => $this->deleted,
         ];
     }
+
+    public function meta(): ResponseMetaInformation
+    {
+        return $this->meta;
+    }
 }