feat: add assistant resource and start session endpoint

Author: andrepimpao

src/Entity/Assistant/Answer.php

@@ -0,0 +1,42 @@
+<?php
+
+namespace ProgrammatorDev\OpenWeatherMap\Entity\Assistant;
+
+use ProgrammatorDev\OpenWeatherMap\Util\EntityTrait;
+
+class Answer
+{
+    use EntityTrait;
+
+    private string $answer;
+
+    private string $sessionId;
+
+    /** @var WeatherData[] */
+    private array $data = [];
+
+    public function __construct(array $data)
+    {
+        $this->answer = $data['answer'];
+        $this->sessionId = $data['session_id'];
+
+        if (!empty($data['data'])) {
+            $this->data = $this->createEntityKeyList(WeatherData::class, $data['data']);
+        }
+    }
+
+    public function getAnswer(): string
+    {
+        return $this->answer;
+    }
+
+    public function getSessionId(): string
+    {
+        return $this->sessionId;
+    }
+
+    public function getData(): array
+    {
+        return $this->data;
+    }
+}

src/Entity/Assistant/WeatherData.php

@@ -0,0 +1,62 @@
+<?php
+
+namespace ProgrammatorDev\OpenWeatherMap\Entity\Assistant;
+
+use ProgrammatorDev\OpenWeatherMap\Entity\BaseWeather;
+
+class WeatherData extends BaseWeather
+{
+    private string $locationName;
+
+    private float $temperature;
+
+    private float $temperatureFeelsLike;
+
+    private int $visibility;
+
+    private \DateTimeImmutable $sunriseAt;
+
+    private \DateTimeImmutable $sunsetAt;
+
+    public function __construct(string $location, array $data)
+    {
+        parent::__construct($data);
+
+        $this->locationName = $location;
+        $this->temperature = $data['temp'];
+        $this->temperatureFeelsLike = $data['feels_like'];
+        $this->visibility = $data['visibility'];
+        $this->sunriseAt = \DateTimeImmutable::createFromFormat('U', $data['sunrise']);
+        $this->sunsetAt = \DateTimeImmutable::createFromFormat('U', $data['sunset']);
+    }
+
+    public function getLocationName(): string
+    {
+        return $this->locationName;
+    }
+
+    public function getTemperature(): float
+    {
+        return $this->temperature;
+    }
+
+    public function getTemperatureFeelsLike(): float
+    {
+        return $this->temperatureFeelsLike;
+    }
+
+    public function getVisibility(): int
+    {
+        return $this->visibility;
+    }
+
+    public function getSunriseAt(): \DateTimeImmutable
+    {
+        return $this->sunriseAt;
+    }
+
+    public function getSunsetAt(): \DateTimeImmutable
+    {
+        return $this->sunsetAt;
+    }
+}

src/Entity/OneCall/BaseWeather.php renamed to src/Entity/BaseWeather.php

@@ -1,9 +1,7 @@
 <?php
 
-namespace ProgrammatorDev\OpenWeatherMap\Entity\OneCall;
+namespace ProgrammatorDev\OpenWeatherMap\Entity;
 
-use ProgrammatorDev\OpenWeatherMap\Entity\Condition;
-use ProgrammatorDev\OpenWeatherMap\Entity\Wind;
 use ProgrammatorDev\OpenWeatherMap\Util\EntityTrait;
 
 class BaseWeather

src/Entity/OneCall/DayData.php

@@ -2,6 +2,8 @@
 
 namespace ProgrammatorDev\OpenWeatherMap\Entity\OneCall;
 
+use ProgrammatorDev\OpenWeatherMap\Entity\BaseWeather;
+
 class DayData extends BaseWeather
 {
     private Temperature $temperature;

src/Entity/OneCall/HourData.php

@@ -2,6 +2,8 @@
 
 namespace ProgrammatorDev\OpenWeatherMap\Entity\OneCall;
 
+use ProgrammatorDev\OpenWeatherMap\Entity\BaseWeather;
+
 class HourData extends BaseWeather
 {
     private float $temperature;

src/Entity/OneCall/WeatherData.php

@@ -2,6 +2,8 @@
 
 namespace ProgrammatorDev\OpenWeatherMap\Entity\OneCall;
 
+use ProgrammatorDev\OpenWeatherMap\Entity\BaseWeather;
+
 class WeatherData extends BaseWeather
 {
     private float $temperature;

src/OpenWeatherMap.php

@@ -13,6 +13,7 @@
 use ProgrammatorDev\OpenWeatherMap\Exception\UnexpectedErrorException;
 use ProgrammatorDev\OpenWeatherMap\Language\Language;
 use ProgrammatorDev\OpenWeatherMap\Resource\AirPollutionResource;
+use ProgrammatorDev\OpenWeatherMap\Resource\AssistantResource;
 use ProgrammatorDev\OpenWeatherMap\Resource\GeocodingResource;
 use ProgrammatorDev\OpenWeatherMap\Resource\OneCallResource;
 use ProgrammatorDev\OpenWeatherMap\Resource\WeatherResource;
@@ -21,12 +22,12 @@
 
 class OpenWeatherMap extends Api
 {
-    private array $options;
+    public readonly array $options;
 
     private OptionsResolver $optionsResolver;
 
     public function __construct(
-        #[\SensitiveParameter] private readonly string $apiKey,
+        #[\SensitiveParameter] public readonly string $apiKey,
         array $options = []
     )
     {
@@ -38,6 +39,11 @@ public function __construct(
         $this->configureApi();
     }
 
+    public function assistant(): AssistantResource
+    {
+        return new AssistantResource($this);
+    }
+
     public function oneCall(): OneCallResource
     {
         return new OneCallResource($this);

src/Resource/AssistantResource.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace ProgrammatorDev\OpenWeatherMap\Resource;
+
+use Http\Message\Authentication\Header;
+use ProgrammatorDev\Api\Method;
+use ProgrammatorDev\OpenWeatherMap\Entity\Assistant\Answer;
+use Psr\Http\Client\ClientExceptionInterface;
+
+class AssistantResource extends Resource
+{
+    /**
+     * Start a new session with the Weather AI Assistant and enter a prompt
+     *
+     * @throws ClientExceptionInterface
+     */
+    public function startSession(string $prompt): Answer
+    {
+        $this->api->setAuthentication(new Header('X-Api-Key', $this->api->apiKey));
+
+        $data = $this->api->request(
+            method: Method::POST,
+            path: '/assistant/session',
+            body: json_encode(['prompt' => $prompt])
+        );
+
+        return new Answer($data);
+    }
+}

src/Util/EntityTrait.php

@@ -10,4 +10,11 @@ private function createEntityList(string $entityClass, array $list): array
             return new $entityClass($data);
         }, $list);
     }
+
+    private function createEntityKeyList(string $entityClass, array $list): array
+    {
+        return array_map(function(array $data, int|string $key) use ($entityClass) {
+            return new $entityClass($key, $data);
+        }, $list, array_keys($list));
+    }
 }