From ceee6f0aec63f6020efe5e969d9e359a6960d3b6 Mon Sep 17 00:00:00 2001
From: Daniel Hofheinz <daniel@danielhofheinz.com>
Date: Sun, 5 Oct 2025 21:43:29 -0700
Subject: [PATCH] docs(files): clarify files.content returns Response object

Updated JSDoc for files.content() to explicitly document that it
returns a Response object and provide examples showing how to
consume the content using .text(), .blob(), or .arrayBuffer().

Fixes #958
---
 examples/file-content-retrieval.ts | 45 ++++++++++++++++++++++++++++++
 src/resources/files.ts             | 19 ++++++++++++-
 2 files changed, 63 insertions(+), 1 deletion(-)
 create mode 100755 examples/file-content-retrieval.ts

diff --git a/examples/file-content-retrieval.ts b/examples/file-content-retrieval.ts
new file mode 100755
index 000000000..fcb6b86e7
--- /dev/null
+++ b/examples/file-content-retrieval.ts
@@ -0,0 +1,45 @@
+#!/usr/bin/env -S npm run tsn -T
+
+/**
+ * Demonstrates how to retrieve and consume file content from OpenAI.
+ *
+ * The files.content() method returns a Response object, which can be
+ * consumed in different formats depending on the file type.
+ */
+
+import OpenAI from 'openai';
+
+const client = new OpenAI({
+  apiKey: process.env['OPENAI_API_KEY'],
+});
+
+async function main() {
+  // Example 1: Retrieve text file content (e.g., JSONL for fine-tuning)
+  {
+    console.log('Fetching text file content...');
+    const response = await client.files.content('file-abc123');
+    const textContent = await response.text();
+    console.log('File content as text:', textContent);
+  }
+
+  // Example 2: Retrieve binary file content (e.g., images)
+  {
+    console.log('Fetching binary file content...');
+    const response = await client.files.content('file-xyz789');
+    const blobContent = await response.blob();
+    console.log('File content as blob:', blobContent);
+  }
+
+  // Example 3: Retrieve as ArrayBuffer for low-level operations
+  {
+    console.log('Fetching file as ArrayBuffer...');
+    const response = await client.files.content('file-def456');
+    const buffer = await response.arrayBuffer();
+    console.log('File size in bytes:', buffer.byteLength);
+  }
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});
diff --git a/src/resources/files.ts b/src/resources/files.ts
index ef6873221..cf6b1a849 100644
--- a/src/resources/files.ts
+++ b/src/resources/files.ts
@@ -64,7 +64,24 @@ export class Files extends APIResource {
   }
 
   /**
-   * Returns the contents of the specified file.
+   * Returns the contents of the specified file as a Response object.
+   *
+   * The Response object provides methods to consume the file content in different formats:
+   * - `.text()` - Returns file content as a string
+   * - `.blob()` - Returns file content as a Blob
+   * - `.arrayBuffer()` - Returns file content as an ArrayBuffer
+   *
+   * @example
+   * ```ts
+   * // Get file content as text (e.g., for JSONL files)
+   * const response = await client.files.content('file-abc123');
+   * const text = await response.text();
+   * console.log(text);
+   *
+   * // Get file content as blob (e.g., for images)
+   * const response = await client.files.content('file-abc123');
+   * const blob = await response.blob();
+   * ```
    */
   content(fileID: string, options?: RequestOptions): APIPromise<Response> {
     return this._client.get(path`/files/${fileID}/content`, {