From 73f9a0ec299d828a0730e1719a7448d522019f0b Mon Sep 17 00:00:00 2001
From: Guilherme Souza <guilherme@supabase.io>
Date: Tue, 16 Dec 2025 07:54:57 -0300
Subject: [PATCH] feat(storage): add support for additional query items in
 download method

---
 Sources/Storage/StorageFileApi.swift         | 15 ++++++++---
 Tests/StorageTests/StorageFileAPITests.swift | 28 ++++++++++++++++++++
 2 files changed, 39 insertions(+), 4 deletions(-)

diff --git a/Sources/Storage/StorageFileApi.swift b/Sources/Storage/StorageFileApi.swift
index 5ec49be97..de8a18231 100644
--- a/Sources/Storage/StorageFileApi.swift
+++ b/Sources/Storage/StorageFileApi.swift
@@ -35,7 +35,7 @@ enum FileUpload {
     }
 
     switch self {
-    case let .data(data):
+    case .data(let data):
       formData.append(
         data,
         withName: "",
@@ -43,7 +43,7 @@ enum FileUpload {
         mimeType: options.contentType ?? mimeType(forPathExtension: path.pathExtension)
       )
 
-    case let .url(url):
+    case .url(let url):
       formData.append(url, withName: "")
     }
   }
@@ -422,15 +422,22 @@ public class StorageFileApi: StorageApi, @unchecked Sendable {
   /// - Parameters:
   ///   - path: The file path to be downloaded, including the path and file name. For example `folder/image.png`.
   ///   - options: Transform the asset before serving it to the client.
+  ///   - additionalQueryItems: Additional query items to be added to the request.
+  /// - Returns: The data of the downloaded file.
   @discardableResult
   public func download(
     path: String,
-    options: TransformOptions? = nil
+    options: TransformOptions? = nil,
+    query additionalQueryItems: [URLQueryItem]? = nil
   ) async throws -> Data {
-    let queryItems = options?.queryItems ?? []
+    var queryItems = options?.queryItems ?? []
     let renderPath = options != nil ? "render/image/authenticated" : "object"
     let _path = _getFinalPath(path)
 
+    if let additionalQueryItems {
+      queryItems.append(contentsOf: additionalQueryItems)
+    }
+
     return try await execute(
       HTTPRequest(
         url: configuration.url
diff --git a/Tests/StorageTests/StorageFileAPITests.swift b/Tests/StorageTests/StorageFileAPITests.swift
index d407e8b23..f8a8f9033 100644
--- a/Tests/StorageTests/StorageFileAPITests.swift
+++ b/Tests/StorageTests/StorageFileAPITests.swift
@@ -581,6 +581,34 @@ final class StorageFileAPITests: XCTestCase {
     XCTAssertEqual(data, Data("hello world".utf8))
   }
 
+  func testDownloadWithAdditionalQuery() async throws {
+    Mock(
+      url: url.appendingPathComponent("object/bucket/file.txt"),
+      ignoreQuery: true,
+      statusCode: 200,
+      data: [
+        .get: Data("hello world".utf8)
+      ]
+    )
+    .snapshotRequest {
+      #"""
+      curl \
+      	--header "X-Client-Info: storage-swift/0.0.0" \
+      	--header "apikey: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZS1kZW1vIiwicm9sZSI6ImFub24iLCJleHAiOjE5ODM4MTI5OTZ9.CRXP1A7WOeoJeXxjNni43kdQwgnWNReilDMblYTn_I0" \
+      	"http://localhost:54321/storage/v1/object/bucket/file.txt?version=1"
+      """#
+    }
+    .register()
+
+    let data = try await storage.from("bucket")
+      .download(
+        path: "file.txt",
+        query: [URLQueryItem(name: "version", value: "1")]
+      )
+
+    XCTAssertEqual(data, Data("hello world".utf8))
+  }
+
   func testDownload_withOptions() async throws {
     let imageData = try! Data(
       contentsOf: Bundle.module.url(forResource: "sadcat", withExtension: "jpg")!)