Implement hf_token support, viewApi, and unit tests

- Wire hf_token as Authorization Bearer header on all HTTP and WebSocket
  requests via RemoteClient
- Add viewApi() method to Client that calls GET /info endpoint
- Add 16 unit tests using Guzzle MockHandler (client construction,
  auth headers, viewApi, predict, client options, events, DTOs)
- Replace live API tests with deterministic mocked tests
- Update README with comprehensive documentation and examples

Author: ikarolaborda

README.md

@@ -10,13 +10,11 @@ A PHP client to call [Gradio](https://www.gradio.app) APIs.
 - [x] HTTP and WS support
 - [x] `predict`
 - [x] getConfig
-- [ ] client options
-- [ ] hf_token support
-- [ ] viewApi
+- [x] client options
+- [x] hf_token support
+- [x] viewApi
 - [x] Finish event system
-- [ ] Add tests
-- [ ] Add more examples
-- [ ] Add documentation
+- [x] Add tests
 
 ## Installation
 
@@ -28,13 +26,157 @@ composer require sergix44/gradio-client-php
 
 ## Usage
 
+### Basic Usage
+
 ```php
 use SergiX44\Gradio\Client;
 
 $client = new Client('https://my-special.hf.space');
 
 $result = $client->predict(['arg', 1, 2], apiName: 'myFunction');
 
+$outputs = $result->getOutputs(); // returns array of all outputs
+$first = $result->getOutput(0);   // returns a single output by index
+```
+
+### Hugging Face Token Authentication
+
+To access private Hugging Face Spaces, pass your HF token:
+
+```php
+use SergiX44\Gradio\Client;
+
+$client = new Client('https://my-private.hf.space', hfToken: 'hf_your_token_here');
+
+$result = $client->predict(['hello'], apiName: 'chat');
+```
+
+The token is automatically sent as a Bearer token in the `Authorization` header on all HTTP and WebSocket requests.
+
+### Viewing Available API Endpoints
+
+Use `viewApi()` to inspect the available API endpoints, their parameters, and return types:
+
+```php
+use SergiX44\Gradio\Client;
+
+$client = new Client('https://my-special.hf.space');
+
+$apiInfo = $client->viewApi();
+
+// Returns an array with 'named_endpoints' and 'unnamed_endpoints'
+// Each endpoint includes parameter and return type information
+print_r($apiInfo);
+```
+
+### Client Options
+
+You can pass custom HTTP client options (Guzzle options) to customize the underlying HTTP client:
+
+```php
+use SergiX44\Gradio\Client;
+
+$client = new Client('https://my-special.hf.space', httpClientOptions: [
+    'timeout' => 30,
+    'headers' => [
+        'X-Custom-Header' => 'value',
+    ],
+    'proxy' => 'http://proxy.example.com:8080',
+]);
+```
+
+### Using Function Index
+
+If you know the function index instead of the API name, you can use `fnIndex`:
+
+```php
+$result = $client->predict(['input'], fnIndex: 0);
+```
+
+### Raw Response
+
+To get the raw decoded response instead of an `Output` DTO:
+
+```php
+$result = $client->predict(['input'], apiName: 'myFunction', raw: true);
+// $result is an associative array
+```
+
+### Event System
+
+You can register callbacks for various events during the prediction process:
+
+```php
+use SergiX44\Gradio\Client;
+use SergiX44\Gradio\DTO\Messages\Estimation;
+use SergiX44\Gradio\DTO\Messages\ProcessCompleted;
+
+$client = new Client('https://my-special.hf.space');
+
+// Called when a prediction is submitted
+$client->onSubmit(function (array $payload) {
+    echo "Submitted!\n";
+});
+
+// Called when queue position is estimated
+$client->onQueueEstimation(function (Estimation $estimation) {
+    echo "Queue position: {$estimation->rank}\n";
+});
+
+// Called when processing starts
+$client->onProcessStarts(function () {
+    echo "Processing started\n";
+});
+
+// Called when processing completes (success or failure)
+$client->onProcessCompleted(function (ProcessCompleted $message) {
+    echo "Completed: " . ($message->success ? 'success' : 'failed') . "\n";
+});
+
+// Called only on success
+$client->onProcessSuccess(function (ProcessCompleted $message) {
+    $output = $message->output;
+});
+
+// Called only on failure
+$client->onProcessFailed(function (ProcessCompleted $message) {
+    echo "Failed!\n";
+});
+
+// Called when the queue is full
+$client->onQueueFull(function () {
+    echo "Queue is full!\n";
+});
+
+// Called during streaming/generating
+$client->onProcessGenerating(function () {
+    echo "Generating...\n";
+});
+
+$result = $client->predict(['input'], apiName: 'myFunction');
+```
+
+### Accessing Config
+
+```php
+$config = $client->getConfig();
+
+echo $config->version;   // Gradio version
+echo $config->protocol;  // 'sse_v3', 'ws', etc.
+echo $config->title;     // App title
+```
+
+### File Upload
+
+You can pass file paths or resources as arguments, and they will be automatically encoded as base64:
+
+```php
+// Using a file path
+$result = $client->predict(['/path/to/image.png'], apiName: 'classify');
+
+// Using a resource
+$stream = fopen('/path/to/audio.mp3', 'r');
+$result = $client->predict([$stream], apiName: 'transcribe');
 ```
 
 ## Testing

src/Client.php

@@ -29,21 +29,20 @@ class Client extends RemoteClient
 
     private const HTTP_CONFIG = 'config';
 
+    private const HTTP_API_INFO = 'info';
+
     protected Config $config;
 
     private string $sessionHash;
 
     private array $endpoints = [];
 
-    private ?string $hfToken;
-
     public function __construct(string $src, ?string $hfToken = null, ?Config $config = null, array $httpClientOptions = [])
     {
-        parent::__construct($src, $httpClientOptions);
+        parent::__construct($src, $hfToken, $httpClientOptions);
         $this->config = $config ?? $this->http('get', self::HTTP_CONFIG, dto: Config::class);
         $this->loadEndpoints($this->config->dependencies);
         $this->sessionHash = substr(md5(microtime()), 0, 11);
-        $this->hfToken = $hfToken;
     }
 
     protected function loadEndpoints(array $dependencies): void
@@ -62,6 +61,11 @@ public function getConfig(): Config
         return $this->config;
     }
 
+    public function viewApi(): array
+    {
+        return $this->http('get', self::HTTP_API_INFO);
+    }
+
     public function predict(array $arguments, ?string $apiName = null, ?int $fnIndex = null, bool $raw = false, ?int $triggerId = null): Output|array|null
     {
         if ($apiName === null && $fnIndex === null) {
@@ -129,19 +133,13 @@ private function preparePayload(array $arguments): array
         }, $arguments);
     }
 
-    /**
-     * @throws GradioException
-     * @throws QueueFullException
-     * @throws \JsonException
-     */
     private function websocketLoop(Endpoint $endpoint, array $payload): ?Output
     {
         $ws = $this->ws(self::QUEUE_JOIN);
 
         while (true) {
             $data = $ws->receive();
 
-            // why sometimes $data is null?
             if ($data === null) {
                 continue;
             }
@@ -231,10 +229,7 @@ private function sseLoop(Endpoint $endpoint, array $payload, string $protocol, ?
                 continue;
             }
 
-            // read second \n
             $response->getBody()->read(1);
-
-            // remove data:
             $buffer = str_replace('data: ', '', $buffer);
             $message = $this->hydrator->hydrateWithJson(Message::class, $buffer);
 

src/Client/RemoteClient.php

@@ -17,7 +17,9 @@ abstract class RemoteClient extends RegisterEvents
 
     protected HydratorInterface $hydrator;
 
-    public function __construct(string $src, array $httpClientOptions = [])
+    private ?string $hfToken;
+
+    public function __construct(string $src, ?string $hfToken = null, array $httpClientOptions = [])
     {
         if (
             ! str_starts_with($src, 'http://') &&
@@ -29,15 +31,22 @@ public function __construct(string $src, array $httpClientOptions = [])
         }
 
         $this->src = str_ends_with($src, '/') ? $src : "{$src}/";
+        $this->hfToken = $hfToken;
 
         $this->hydrator = new Hydrator();
 
+        $defaultHeaders = [
+            'User-Agent' => 'gradio_client_php/1.0',
+            'Accept' => 'application/json',
+        ];
+
+        if ($this->hfToken !== null) {
+            $defaultHeaders['Authorization'] = 'Bearer ' . $this->hfToken;
+        }
+
         $this->httpClient = new Guzzle(array_merge([
             'base_uri' => str_replace('ws', 'http', $this->src),
-            'headers' => [
-                'User-Agent' => 'gradio_client_php/1.0',
-                'Accept' => 'application/json',
-            ],
+            'headers' => $defaultHeaders,
         ], $httpClientOptions));
     }
 
@@ -59,6 +68,10 @@ protected function httpRaw(string $method, string $uri, array $params = [], arra
 
     protected function ws(string $uri, array $options = []): EnhancedClient
     {
+        if ($this->hfToken !== null && ! isset($options['headers']['Authorization'])) {
+            $options['headers']['Authorization'] = 'Bearer ' . $this->hfToken;
+        }
+
         return new EnhancedClient(str_replace('http', 'ws', $this->src).$uri, $options);
     }