Fix(OpenAI): Add filename property to OutputMessageContentOutputTextAnnotationsFileCitation (#696)

* Add `filename` property to OutputMessageContentOutputTextAnnotationsFileCitation

* add test for `OutputMessageContentOutputTextAnnotationsFileCitation`

---------

Co-authored-by: Nate Brown <[email protected]>

Author: qwertyquest

src/Responses/Responses/Output/OutputMessageContentOutputTextAnnotationsFileCitation.php

@@ -9,14 +9,14 @@
 use OpenAI\Testing\Responses\Concerns\Fakeable;
 
 /**
- * @phpstan-type FileCitationType array{file_id: string, index: int, type: 'file_citation'}
+ * @phpstan-type FileCitationType array{file_id: string, filename: string, index: int, type: 'file_citation'}
  *
  * @implements ResponseContract<FileCitationType>
  */
 final class OutputMessageContentOutputTextAnnotationsFileCitation implements ResponseContract
 {
     /**
-     * @use ArrayAccessible<array{file_id: string, index: int, type: 'file_citation'}>
+     * @use ArrayAccessible<array{file_id: string, filename: string, index: int, type: 'file_citation'}>
      */
     use ArrayAccessible;
 
@@ -27,17 +27,19 @@ final class OutputMessageContentOutputTextAnnotationsFileCitation implements Res
      */
     private function __construct(
         public readonly string $fileId,
+        public readonly string $filename,
         public readonly int $index,
         public readonly string $type,
     ) {}
 
     /**
-     * @param  array{file_id: string, index: int, type: 'file_citation'}  $attributes
+     * @param  array{file_id: string, filename: string, index: int, type: 'file_citation'}  $attributes
      */
     public static function from(array $attributes): self
     {
         return new self(
             fileId: $attributes['file_id'],
+            filename: $attributes['filename'],
             index: $attributes['index'],
             type: $attributes['type'],
         );
@@ -50,6 +52,7 @@ public function toArray(): array
     {
         return [
             'file_id' => $this->fileId,
+            'filename' => $this->filename,
             'index' => $this->index,
             'type' => $this->type,
         ];

tests/Fixtures/Responses.php

@@ -579,6 +579,18 @@ function outputAnnotationMessage(): array
                         'type' => 'url_citation',
                         'url' => 'https://.../?utm_source=chatgpt.com',
                     ],
+                    [
+                        'file_id' => 'file-8aTRXYAhp5PbDF5R5P9Rky',
+                        'filename' => 'document.pdf',
+                        'index' => 138,
+                        'type' => 'file_citation',
+                    ],
+                    [
+                        'file_id' => 'file-9cPRXMKyn1BmDT1K9J8Xxa',
+                        'filename' => 'example-file.md',
+                        'index' => 294,
+                        'type' => 'file_citation',
+                    ],
                 ],
                 'text' => 'As of today, March 9, 2025, one notable positive news story...',
                 'type' => 'output_text',

tests/Responses/Responses/Output/OutputMessageContentOutputTextAnnotationsFileCitation.php

@@ -0,0 +1,46 @@
+<?php
+
+use OpenAI\Responses\Responses\Output\OutputMessageContentOutputTextAnnotationsFileCitation;
+
+test('from', function () {
+    $annotation = outputAnnotationMessage()['content'][0]['annotations'][3];
+    $response = OutputMessageContentOutputTextAnnotationsFileCitation::from($annotation);
+
+    expect($response)
+        ->toBeInstanceOf(OutputMessageContentOutputTextAnnotationsFileCitation::class)
+        ->fileId->toBe('file-8aTRXYAhp5PbDF5R5P9Rky')
+        ->filename->toBe('document.pdf')
+        ->index->toBe(138)
+        ->type->toBe('file_citation');
+});
+
+test('from with second file citation', function () {
+    $annotation = outputAnnotationMessage()['content'][0]['annotations'][4];
+    $response = OutputMessageContentOutputTextAnnotationsFileCitation::from($annotation);
+
+    expect($response)
+        ->toBeInstanceOf(OutputMessageContentOutputTextAnnotationsFileCitation::class)
+        ->fileId->toBe('file-9cPRXMKyn1BmDT1K9J8Xxa')
+        ->filename->toBe('example-file.md')
+        ->index->toBe(294)
+        ->type->toBe('file_citation');
+});
+
+test('as array accessible', function () {
+    $annotation = outputAnnotationMessage()['content'][0]['annotations'][3];
+    $response = OutputMessageContentOutputTextAnnotationsFileCitation::from($annotation);
+
+    expect($response['file_id'])->toBe('file-8aTRXYAhp5PbDF5R5P9Rky')
+        ->and($response['filename'])->toBe('document.pdf')
+        ->and($response['index'])->toBe(138)
+        ->and($response['type'])->toBe('file_citation');
+});
+
+test('to array', function () {
+    $annotation = outputAnnotationMessage()['content'][0]['annotations'][3];
+    $response = OutputMessageContentOutputTextAnnotationsFileCitation::from($annotation);
+
+    expect($response->toArray())
+        ->toBeArray()
+        ->toBe($annotation);
+});