feat(OpenAI): add support for response cancel (#588)

Author: iBotPeaches

README.md

@@ -254,6 +254,19 @@ $response->truncation; // 'disabled'
 $response->toArray(); // ['id' => 'resp_67ccd2bed1ec8190b14f964abc054267', ...]
 ```
 
+### `cancel`
+
+Cancel a model response (background request) with the given ID.
+
+```php
+$response = $client->responses()->cancel('resp_67ccd2bed1ec8190b14f964abc054267');
+
+$response->id; // 'resp_67ccd2bed1ec8190b14f964abc054267'
+$response->status; // 'canceled'
+
+$response->toArray(); // ['id' => 'resp_67ccd2bed1ec8190b14f964abc054267', 'status' => 'canceled', ...]
+```
+
 ### `delete`
 
 Deletes a model response with the given ID.

src/Resources/Responses.php

@@ -80,6 +80,21 @@ public function retrieve(string $id): RetrieveResponse
         return RetrieveResponse::from($response->data(), $response->meta());
     }
 
+    /**
+     * Cancels a model response with the given ID. Must be marked as 'background' to be cancellable.
+     *
+     * @see https://platform.openai.com/docs/api-reference/responses/cancel
+     */
+    public function cancel(string $id): RetrieveResponse
+    {
+        $payload = Payload::cancel('responses', $id);
+
+        /** @var Response<RetrieveResponseType> $response */
+        $response = $this->transporter->requestObject($payload);
+
+        return RetrieveResponse::from($response->data(), $response->meta());
+    }
+
     /**
      * Deletes a model response with the given ID.
      *

tests/Resources/Responses.php

@@ -201,3 +201,20 @@
     expect($result->meta())
         ->toBeInstanceOf(MetaInformation::class);
 });
+
+test('cancel', function () {
+    $client = mockClient('POST', 'responses/resp_67ccf18ef5fc8190b16dbee19bc54e5f087bb177ab789d5c/cancel', [
+    ], \OpenAI\ValueObjects\Transporter\Response::from(retrieveResponseResource(), metaHeaders()));
+
+    $result = $client->responses()->cancel('resp_67ccf18ef5fc8190b16dbee19bc54e5f087bb177ab789d5c');
+
+    expect($result)
+        ->toBeInstanceOf(RetrieveResponse::class)
+        ->id->toBe('resp_67ccf18ef5fc8190b16dbee19bc54e5f087bb177ab789d5c')
+        ->object->toBe('response')
+        ->createdAt->toBe(1741484430)
+        ->status->toBe('completed');
+
+    expect($result->meta())
+        ->toBeInstanceOf(MetaInformation::class);
+});