feat(storage)!: storage v3

[grdsdev]

This PR is a major overhaul of the Storage module — Storage v3. It replaces the old class hierarchy with a modern, value-type-forward Swift API, introduces typed domain values, adds upload progress reporting, rewrites error handling, and ships comprehensive DocC documentation.

Breaking change — this PR renames types, changes parameter types, and removes or internalises several APIs. Migration notes are in each section below.

---

Architecture

New StorageClient replaces StorageApi + StorageBucketApi

The old StorageApi base class and StorageBucketApi subclass are removed. All bucket and file operations now live on the new StorageClient struct.

• StorageClient.url is a first-class initialiser parameter, no longer nested inside StorageClientConfiguration.
• JSON encoder/decoder are internal to StorageClient with a fixed snake_case strategy and are no longer user-configurable via StorageClientConfiguration.
• @unchecked Sendable classes are gone; the new types are proper Sendable structs where needed.
• HTTP error translation (translateStorageError) is now internal to StorageClient. HTTPError no longer leaks out of Storage operations — callers always receive StorageError.

StorageFileApi → StorageFileAPI

The file API type is renamed to follow Swift's acronym capitalisation convention. The old StorageFileApi.swift (747 lines) is replaced by StorageFileAPI.swift (1 128 lines) with full typed APIs.

MultipartFormData replaced by MultipartBuilder

The old 717-line Alamofire-derived MultipartFormData class is replaced with a 279-line value-type MultipartBuilder struct:

• Immutable, chainable builder API (addText, addData, addFile, addFileStreamed).
• Supports both in-memory builds (buildInMemory()) and temp-file streaming (buildToTempFile()) for large uploads.
• No third-party code or class-based mutable state.

Types consolidated into Types.swift

BucketOptions, TransformOptions, and several response types that were scattered across individual files are now in a single Types.swift.

---

New Typed Value Types (Breaking)

Old	New	Notes
String (resize mode)	ResizeMode	.cover, .contain, .fill
String? (image format)	ImageFormat?	.origin, .avif, .webp, .jpeg, .png
String (sort order)	SortOrder	.asc, .desc
String? (file size limit)	StorageByteCount?	.bytes(), .kilobytes(), .megabytes(), .gigabytes(), ExpressibleByIntegerLiteral
Bool (download flag)	DownloadBehavior?	.withOriginalName, .named("filename.pdf"); nil = no download

BucketOptions changes

// Before
BucketOptions(public: true, fileSizeLimit: "10485760")

// After
BucketOptions(isPublic: true, fileSizeLimit: .megabytes(10))

• public renamed to isPublic (avoids Swift keyword collision).
• fileSizeLimit changed from String? to StorageByteCount?.

TransformOptions changes

// Before
TransformOptions(resize: "cover", format: "origin")

// After
TransformOptions(resize: .cover, format: .origin)

SortBy.order change

// Before
SortBy(column: "name", order: "asc")

// After
SortBy(column: "name", order: .asc)

createSignedURL / createSignedURLs changes

// Before
api.createSignedURL(path: "file.png", expiresIn: 60, download: true)

// After — download with original filename
api.createSignedURL(path: "file.png", expiresIn: .seconds(60), download: .withOriginalName)

// After — download with custom filename
api.createSignedURL(path: "file.png", expiresIn: .seconds(60), download: .named("annual-2024.pdf"))

expiresIn now takes Duration instead of a raw Int (seconds). The download parameter uses DownloadBehavior? instead of Bool — pass nil (the default) to omit the download query parameter.

---

Other API Changes (Breaking)

• FileObjectV2 → FileInfo: the v2 response type is renamed to the simpler FileInfo.
• FileInfo.id and FileUploadResponse.id are now UUID: Storage object IDs are gen_random_uuid() in the database, so these are now properly typed.
• SearchOptions.prefix is now internal: it was never meant to be set directly by callers.
• FileOptions.duplex and FileOptions.headers removed: these were implementation details that leaked into the public API.
• uploadFile convenience removed: the main upload overloads cover all cases.

---

Upload Progress Reporting

Upload methods now accept an optional trailing closure for progress:

try await api.upload(path: "video.mp4", file: data) { progress in
    print("\(progress.fractionCompleted * 100)% uploaded")
}

New UploadProgress type exposes totalBytesSent, totalBytesExpectedToSend, and fractionCompleted.

---

Typed Error Handling

do {
    let data = try await api.download(path: "secret.png")
} catch let error as StorageError {
    if error.isNotFound {
        // handle 404
    } else if error.isUnauthorized {
        // handle 401
    }
    print(error.errorCode) // StorageErrorCode
    print(error.statusCode) // Int?
}

• New StorageErrorCode type — RawRepresentable with static constants for all known server error strings (e.g. .notFound, .objectNotFound, .bucketNotFound). Adding new constants is never a breaking change.
• StorageError gains: errorCode: StorageErrorCode, statusCode: Int?, underlyingResponse, underlyingData, isNotFound, isUnauthorized.
• StorageError no longer conforms to Decodable — JSON decoding is an internal implementation detail.
• exists(path:) is simplified to a single catch clause using isNotFound.

---

Documentation

All public types, properties, initialisers, and methods in the Storage module now have DocC-style doc comments with parameter lists, return/throws descriptions, and ## Example code blocks. Also fixes a pre-existing bug where the fileSizeLimit and allowedMimeTypes doc comments were swapped in BucketOptions.

---

Other Changes

• Package.swift: macOS minimum version bumped from 12 → 13.
• Mocker: updated from 1.7.0 → 1.7.1.
• Linux: FoundationNetworking import added to StorageFileAPI for Linux builds.
• .gitignore: ignores .claude/, .claire/, docs/superpowers/.

---

Test Coverage

New test file	What it covers
MultipartBuilderTests.swift	In-memory and temp-file builds, text/data/file parts
StorageByteCountTests.swift	Factory methods, arithmetic, ExpressibleByIntegerLiteral
UploadProgressTests.swift	fractionCompleted, edge cases
ValueTypesTests.swift	ResizeMode, ImageFormat, SortOrder, DownloadBehavior raw values

Existing StorageErrorTests, StorageFileAPITests, StorageBucketAPITests, TransformOptionsTests, BucketOptionsTests, and integration tests are updated for the new APIs.

[grdsdev]

Code review

Found 4 issues:

1. addFileStreamed is a dead API with a misleading contract — it is byte-for-byte identical to addFile, but its doc comment says "for streamed output." A caller who uses addFileStreamed and then calls buildInMemory() will still load the entire file into memory via Data(contentsOf:). The streaming is a property of which build* method is chosen, not which add* method. The method is also never called anywhere in the codebase.

supabase-swift/Sources/Storage/MultipartBuilder.swift

Lines 64 to 77 in e9a99e7

	/// Add a file field to the multipart payload (for streamed output)
	func addFileStreamed(
	name: String,
	fileURL: URL,
	fileName: String? = nil,
	mimeType: String? = nil
	) -> MultipartBuilder {
	// For now, same as addFile - streaming happens in buildToTempFile
	var builder = self
	builder.parts.append(
	.file(name: name, fileURL: fileURL, fileName: fileName, mimeType: mimeType))
	return builder
	}

2. isNotFound includes statusCode == 400, which means exists() silently returns false for any HTTP 400 Bad Request (e.g. malformed path, missing required header, payload validation error). Callers will think a file is absent when the real problem is a bad request, making those errors very hard to debug. The 400 check appears intentional (it's documented in the property's doc comment), but the broader isNotFound being part of the public API means this semantics also bleeds into any user code that switches on error.isNotFound.

supabase-swift/Sources/Storage/StorageError.swift

Lines 151 to 161 in e9a99e7

	/// `true` when the error indicates that the requested object or bucket does not exist.
	///
	/// Covers HTTP status codes 400 and 404 as well as the explicit error codes
	/// ``StorageErrorCode/objectNotFound``, ``StorageErrorCode/bucketNotFound``, and
	/// ``StorageErrorCode/notFound``.
	public var isNotFound: Bool {
	statusCode == 400 || statusCode == 404
	|| errorCode == .objectNotFound
	|| errorCode == .bucketNotFound
	|| errorCode == .notFound
	}

3. x-upsert header is not sent for update() (PUT), only for upload() (POST) — the guard if method == .post means a call to update(path:file:options:) with options.upsert = true never actually signals upsert intent to the server. This is inconsistent with _uploadToSignedURL, which unconditionally sends the header regardless of method.

supabase-swift/Sources/Storage/StorageFileAPI.swift

Lines 169 to 173 in e9a99e7

	var headers = multipartHeaders(options: options)
	if method == .post {
	headers[Header.xUpsert] = "\(options.upsert)"
	}

4. ServerErrorResponse.message is non-optional — if the Storage server returns an error body without a message field (e.g. {"error": "unauthorized"}), the entire Decodable decode fails and the error falls back to errorCode: .unknown, discarding the structured error field. Making message optional and falling back to error would preserve the error code in all cases.

supabase-swift/Sources/Storage/StorageClient.swift

Lines 314 to 320 in e9a99e7

	private struct ServerErrorResponse: Decodable {
	let message: String
	let error: String?
	/// The server sends the status code as a JSON string, e.g. `"404"`.
	let statusCode: String?
	}

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}