feat(OpenAI): add Conversation API

README.md

@@ -29,8 +29,10 @@ If you or your business relies on this package, it's important to support the de
 - [Usage](#usage)
   - [Models Resource](#models-resource)
   - [Responses Resource](#responses-resource)
+  - [Responses Conversations Resource](#responses-conversations-resource)
+  - [Responses Conversations Items Resource](#responses-conversations-items-resource)
   - [Containers Resource](#containers-resource)
-  - [Containers Files Resource](#container-files-resource)
+  - [Containers Files Resource](#containers-files-resource)
   - [Chat Resource](#chat-resource)
   - [Audio Resource](#audio-resource)
   - [Embeddings Resource](#embeddings-resource)
@@ -309,6 +311,148 @@ $response->hasMore; // false
 $response->toArray(); // ['object' => 'list', 'data' => [...], ...]
 ```
 
+### `Responses Conversations` Resource
+
+#### `create`
+
+Create a conversation.
+
+```php
+$response = $client->responses()->conversations()->create([
+    'metadata' => ['topic' => 'demo'],
+    'items' => [
+        [
+            'type' => 'message',
+            'role' => 'user',
+            'content' => 'Hello!'
+        ],
+    ],
+]);
+
+$response->id; // 'conv_123'
+$response->object; // 'conversation'
+$response->createdAt; // 1741900000
+$response->metadata; // ['topic' => 'demo']
+
+$response->toArray(); // ['id' => 'conv_123', 'object' => 'conversation', ...]
+```
+
+#### `retrieve`
+
+Retrieve a conversation by ID.
+
+```php
+$response = $client->responses()->conversations()->retrieve('conv_123');
+
+$response->id; // 'conv_123'
+$response->object; // 'conversation'
+$response->createdAt; // 1741900000
+
+$response->toArray(); // ['id' => 'conv_123', 'object' => 'conversation', ...]
+```
+
+#### `update`
+
+Update a conversation by ID.
+
+```php
+$response = $client->responses()->conversations()->update('conv_123', [
+    'metadata' => ['foo' => 'bar'],
+]);
+
+$response->id; // 'conv_123'
+$response->metadata; // ['foo' => 'bar']
+```
+
+#### `delete`
+
+Delete a conversation by ID.
+
+```php
+$response = $client->responses()->conversations()->delete('conv_123');
+
+$response->id; // 'conv_123'
+$response->object; // 'conversation.deleted'
+$response->deleted; // true
+
+$response->toArray(); // ['id' => 'conv_123', 'object' => 'conversation.deleted', 'deleted' => true]
+```
+
+### `Responses Conversations Items` Resource
+
+#### `create`
+
+Create items for a conversation.
+
+```php
+$response = $client->responses()->conversations()->items()->create('conv_123', [
+    'items' => [
+        [
+            'type' => 'message',
+            'role' => 'user',
+            'content' => [['type' => 'input_text', 'text' => 'Hello!']],
+        ],
+        [
+            'type' => 'message',
+            'role' => 'user',
+            'content' => [['type' => 'input_text', 'text' => 'How are you?']],
+        ],
+    ],
+]);
+
+$response->object; // 'list'
+
+foreach ($response->data as $item) {
+    $item->type; // 'message'
+    $item->id; // 'msg_abc'
+    $item->status; // 'completed'
+    $item->role; // 'user'
+}
+
+$response->firstId; // 'msg_abc'
+$response->lastId; // 'msg_abc'
+$response->hasMore; // false
+
+$response->toArray(); // ['object' => 'list', 'data' => [...], ...]
+```
+
+#### `list`
+
+List items for a conversation.
+
+```php
+$response = $client->responses()->conversations()->items()->list('conv_123', [
+    'limit' => 10,
+]);
+
+$response->object; // 'list'
+```
+
+#### `retrieve`
+
+Retrieve a specific item from a conversation.
+
+```php
+$response = $client->responses()->conversations()->items()->retrieve('conv_123', 'msg_abc', [
+    'include' => ['step_details'],
+]);
+
+$response->id; // 'msg_abc'
+$response->type; // 'message'
+$response->status; // 'completed'
+```
+
+#### `delete`
+
+Delete a specific item from a conversation. Returns the updated conversation.
+
+```php
+$response = $client->responses()->conversations()->items()->delete('conv_123', 'msg_abc');
+
+$response->id; // 'conv_123'
+$response->object; // 'conversation'
+```
+
 ### `Containers` Resource
 
 #### `create`

src/Contracts/Resources/ResponsesConversationsContract.php

@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenAI\Contracts\Resources;
+
+use OpenAI\Responses\Responses\Conversations\ConversationDeletedResponse;
+use OpenAI\Responses\Responses\Conversations\ConversationResponse;
+
+interface ResponsesConversationsContract
+{
+    /**
+     * Create a conversation
+     *
+     * @see https://platform.openai.com/docs/api-reference/conversations/create
+     *
+     * @param  array<string, mixed>  $parameters
+     */
+    public function create(array $parameters = []): ConversationResponse;
+
+    /**
+     * Retrieve a conversation by ID
+     *
+     * @see https://platform.openai.com/docs/api-reference/conversations/retrieve
+     */
+    public function retrieve(string $conversationId): ConversationResponse;
+
+    /**
+     * Update a conversation by ID
+     *
+     * @see https://platform.openai.com/docs/api-reference/conversations/update
+     *
+     * @param  array<string, mixed>  $parameters
+     */
+    public function update(string $conversationId, array $parameters): ConversationResponse;
+
+    /**
+     * Delete a conversation by ID
+     *
+     * @see https://platform.openai.com/docs/api-reference/conversations/delete
+     */
+    public function delete(string $conversationId): ConversationDeletedResponse;
+
+    /**
+     * Manage conversation items subresource.
+     *
+     * @see https://platform.openai.com/docs/api-reference/conversations/list-items
+     */
+    public function items(): ResponsesConversationsItemsContract;
+}

src/Contracts/Resources/ResponsesConversationsItemsContract.php

@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenAI\Contracts\Resources;
+
+use OpenAI\Responses\Responses\Conversations\ConversationItem;
+use OpenAI\Responses\Responses\Conversations\ConversationItemList;
+use OpenAI\Responses\Responses\Conversations\ConversationResponse;
+
+interface ResponsesConversationsItemsContract
+{
+    /**
+     * Create items for a conversation
+     *
+     * @see https://platform.openai.com/docs/api-reference/conversations/create-item
+     *
+     * @param  array<string, mixed>  $parameters
+     */
+    public function create(string $conversationId, array $parameters): ConversationItemList;
+
+    /**
+     * List items for a conversation
+     *
+     * @see https://platform.openai.com/docs/api-reference/conversations/list-items
+     *
+     * @param  array<string, mixed>  $parameters
+     */
+    public function list(string $conversationId, array $parameters = []): ConversationItemList;
+
+    /**
+     * Retrieve a specific item from a conversation
+     *
+     * @see https://platform.openai.com/docs/api-reference/conversations/get-item
+     *
+     * @param  array<string, mixed>  $parameters
+     */
+    public function retrieve(string $conversationId, string $itemId, array $parameters = []): ConversationItem;
+
+    /**
+     * Delete a specific item from a conversation. Returns updated Conversation.
+     *
+     * @see https://platform.openai.com/docs/api-reference/conversations/delete-item
+     */
+    public function delete(string $conversationId, string $itemId): ConversationResponse;
+}

src/Resources/Responses.php

@@ -5,6 +5,7 @@
 namespace OpenAI\Resources;
 
 use OpenAI\Contracts\Resources\ResponsesContract;
+use OpenAI\Contracts\Resources\ResponsesConversationsContract;
 use OpenAI\Responses\Responses\CreateResponse;
 use OpenAI\Responses\Responses\CreateStreamedResponse;
 use OpenAI\Responses\Responses\DeleteResponse;
@@ -126,4 +127,14 @@ public function list(string $id, array $parameters = []): ListInputItems
 
         return ListInputItems::from($response->data(), $response->meta());
     }
+
+    /**
+     * Manage the Conversations API under Responses.
+     *
+     * @see https://platform.openai.com/docs/api-reference/conversations
+     */
+    public function conversations(): ResponsesConversationsContract
+    {
+        return new ResponsesConversations($this->transporter);
+    }
 }

src/Resources/ResponsesConversations.php

@@ -0,0 +1,81 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenAI\Resources;
+
+use OpenAI\Contracts\Resources\ResponsesConversationsContract;
+use OpenAI\Contracts\Resources\ResponsesConversationsItemsContract;
+use OpenAI\Responses\Responses\Conversations\ConversationDeletedResponse;
+use OpenAI\Responses\Responses\Conversations\ConversationResponse;
+use OpenAI\ValueObjects\Transporter\Payload;
+use OpenAI\ValueObjects\Transporter\Response;
+
+/**
+ * @phpstan-import-type ConversationType from ConversationResponse
+ * @phpstan-import-type ConversationDeletedType from ConversationDeletedResponse
+ */
+final class ResponsesConversations implements ResponsesConversationsContract
+{
+    use Concerns\Transportable;
+
+    /**
+     * {@inheritdoc}
+     */
+    public function create(array $parameters = []): ConversationResponse
+    {
+        $payload = Payload::create('conversations', $parameters);
+
+        /** @var Response<ConversationType> $response */
+        $response = $this->transporter->requestObject($payload);
+
+        return ConversationResponse::from($response->data(), $response->meta());
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function retrieve(string $conversationId): ConversationResponse
+    {
+        $payload = Payload::retrieve('conversations', $conversationId);
+
+        /** @var Response<ConversationType> $response */
+        $response = $this->transporter->requestObject($payload);
+
+        return ConversationResponse::from($response->data(), $response->meta());
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function update(string $conversationId, array $parameters): ConversationResponse
+    {
+        $payload = Payload::modify('conversations', $conversationId, $parameters);
+
+        /** @var Response<ConversationType> $response */
+        $response = $this->transporter->requestObject($payload);
+
+        return ConversationResponse::from($response->data(), $response->meta());
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function delete(string $conversationId): ConversationDeletedResponse
+    {
+        $payload = Payload::delete('conversations', $conversationId);
+
+        /** @var Response<ConversationDeletedType> $response */
+        $response = $this->transporter->requestObject($payload);
+
+        return ConversationDeletedResponse::from($response->data(), $response->meta());
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function items(): ResponsesConversationsItemsContract
+    {
+        return new ResponsesConversationsItems($this->transporter);
+    }
+}