wehub-resource-sync
361 lines
6.8 KiB
Plaintext
361 lines
6.8 KiB
Plaintext
---
|
|
title: Storage SDK Reference
|
|
description: File upload, download, and management with the InsForge Swift SDK
|
|
---
|
|
|
|
import SwiftSdkInstallation from '/snippets/swift-sdk-installation.mdx';
|
|
|
|
## Installation
|
|
|
|
<SwiftSdkInstallation />
|
|
|
|
## from()
|
|
|
|
Get a file API reference for a bucket.
|
|
|
|
### Example
|
|
|
|
```swift
|
|
let bucket = insforge.storage.from("images")
|
|
```
|
|
|
|
---
|
|
|
|
## Bucket Operations
|
|
|
|
### createBucket()
|
|
|
|
Creates a new storage bucket.
|
|
|
|
```swift
|
|
// Create a public bucket
|
|
try await insforge.storage.createBucket("avatars")
|
|
|
|
// Create a private bucket
|
|
try await insforge.storage.createBucket(
|
|
"documents",
|
|
options: BucketOptions(isPublic: false)
|
|
)
|
|
```
|
|
|
|
### listBuckets()
|
|
|
|
List all bucket names.
|
|
|
|
```swift
|
|
let buckets = try await insforge.storage.listBuckets()
|
|
// ["avatars", "documents", "uploads"]
|
|
```
|
|
|
|
### updateBucket()
|
|
|
|
Update a bucket's visibility.
|
|
|
|
```swift
|
|
try await insforge.storage.updateBucket(
|
|
"documents",
|
|
options: BucketOptions(isPublic: true)
|
|
)
|
|
```
|
|
|
|
### deleteBucket()
|
|
|
|
Delete a bucket.
|
|
|
|
```swift
|
|
try await insforge.storage.deleteBucket("old-bucket")
|
|
```
|
|
|
|
---
|
|
|
|
## upload()
|
|
|
|
Upload a file to the bucket.
|
|
|
|
### Parameters
|
|
|
|
- `path` (String) - The object key/path for the file
|
|
- `data` (Data) - File data to upload
|
|
- `options` (FileOptions, optional) - Upload options including contentType
|
|
|
|
### Examples
|
|
|
|
```swift
|
|
// Upload with specific path
|
|
let imageData = UIImage(named: "photo")?.jpegData(compressionQuality: 0.8)
|
|
let file = try await insforge.storage
|
|
.from("images")
|
|
.upload(
|
|
path: "posts/post-123/cover.jpg",
|
|
data: imageData!,
|
|
options: FileOptions(contentType: "image/jpeg")
|
|
)
|
|
|
|
print("Uploaded: \(file.url)")
|
|
print("Key: \(file.key)")
|
|
|
|
// Upload from file URL
|
|
let fileURL = URL(fileURLWithPath: "/path/to/document.pdf")
|
|
let file = try await insforge.storage
|
|
.from("documents")
|
|
.upload(
|
|
path: "reports/annual-2024.pdf",
|
|
fileURL: fileURL
|
|
)
|
|
|
|
// Upload with auto-generated key
|
|
let file = try await insforge.storage
|
|
.from("uploads")
|
|
.upload(
|
|
data: imageData!,
|
|
fileName: "profile.jpg",
|
|
options: FileOptions(contentType: "image/jpeg")
|
|
)
|
|
```
|
|
|
|
---
|
|
|
|
## download()
|
|
|
|
Download a file as Data.
|
|
|
|
### Example
|
|
|
|
```swift
|
|
// Download file
|
|
let data = try await insforge.storage
|
|
.from("images")
|
|
.download(path: "posts/post-123/cover.jpg")
|
|
|
|
// Convert to UIImage
|
|
if let image = UIImage(data: data) {
|
|
imageView.image = image
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## list()
|
|
|
|
List files in a bucket.
|
|
|
|
### Parameters
|
|
|
|
- `options` (ListOptions, optional) - Options including prefix, limit, offset
|
|
|
|
### Examples
|
|
|
|
```swift
|
|
// List all files
|
|
let files = try await insforge.storage
|
|
.from("images")
|
|
.list()
|
|
|
|
// List with prefix filter
|
|
let userFiles = try await insforge.storage
|
|
.from("images")
|
|
.list(options: ListOptions(prefix: "users/", limit: 50))
|
|
|
|
// Shorthand with prefix
|
|
let files = try await insforge.storage
|
|
.from("images")
|
|
.list(prefix: "posts/", limit: 20, offset: 0)
|
|
|
|
// Iterate results
|
|
for file in files {
|
|
print("Key: \(file.key), Size: \(file.size)")
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## delete()
|
|
|
|
Delete a file from storage.
|
|
|
|
### Example
|
|
|
|
```swift
|
|
// Delete a file
|
|
try await insforge.storage
|
|
.from("images")
|
|
.delete(path: "posts/post-123/cover.jpg")
|
|
|
|
// Delete with database cleanup
|
|
let posts: [Post] = try await insforge.database
|
|
.from("posts")
|
|
.select("id, image_key")
|
|
.eq("id", value: "post-123")
|
|
.execute()
|
|
|
|
if let post = posts.first, let imageKey = post.imageKey {
|
|
// Delete from storage
|
|
try await insforge.storage
|
|
.from("images")
|
|
.delete(path: imageKey)
|
|
|
|
// Clear database reference
|
|
struct PostUpdate: Codable {
|
|
let imageUrl: String?
|
|
let imageKey: String?
|
|
}
|
|
|
|
let _: [Post] = try await insforge.database
|
|
.from("posts")
|
|
.eq("id", value: "post-123")
|
|
.update(PostUpdate(imageUrl: nil, imageKey: nil))
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## getPublicURL()
|
|
|
|
Get a public URL for a file in a public bucket.
|
|
|
|
### Example
|
|
|
|
```swift
|
|
let url = insforge.storage
|
|
.from("images")
|
|
.getPublicURL(path: "posts/post-123/cover.jpg")
|
|
|
|
print("Public URL: \(url)")
|
|
```
|
|
|
|
---
|
|
|
|
## Upload Strategy
|
|
|
|
Get upload strategy for large files (direct or presigned URL).
|
|
|
|
### getUploadStrategy()
|
|
|
|
```swift
|
|
let strategy = try await insforge.storage
|
|
.from("videos")
|
|
.getUploadStrategy(
|
|
filename: "large-video.mp4",
|
|
contentType: "video/mp4",
|
|
size: 104857600 // 100MB
|
|
)
|
|
|
|
if strategy.method == "presigned" {
|
|
// Upload directly to S3 using presigned URL
|
|
print("Upload URL: \(strategy.uploadUrl)")
|
|
print("Key: \(strategy.key)")
|
|
|
|
// After uploading to presigned URL, confirm the upload
|
|
if strategy.confirmRequired {
|
|
let file = try await insforge.storage
|
|
.from("videos")
|
|
.confirmUpload(
|
|
path: strategy.key,
|
|
size: 104857600,
|
|
contentType: "video/mp4"
|
|
)
|
|
}
|
|
}
|
|
```
|
|
|
|
### confirmUpload()
|
|
|
|
Confirm a presigned upload after uploading directly to S3.
|
|
|
|
```swift
|
|
let file = try await insforge.storage
|
|
.from("videos")
|
|
.confirmUpload(
|
|
path: "videos/large-video.mp4",
|
|
size: 104857600,
|
|
contentType: "video/mp4",
|
|
etag: "\"abc123\"" // Optional S3 ETag
|
|
)
|
|
```
|
|
|
|
---
|
|
|
|
## Download Strategy
|
|
|
|
Get download strategy for private files (direct or presigned URL).
|
|
|
|
### getDownloadStrategy()
|
|
|
|
```swift
|
|
let strategy = try await insforge.storage
|
|
.from("documents")
|
|
.getDownloadStrategy(
|
|
path: "private/confidential.pdf",
|
|
expiresIn: 3600 // URL expires in 1 hour
|
|
)
|
|
|
|
if strategy.method == "presigned" {
|
|
// Use presigned URL to download
|
|
print("Download URL: \(strategy.url)")
|
|
print("Expires: \(strategy.expiresAt ?? "N/A")")
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Options Reference
|
|
|
|
### FileOptions
|
|
|
|
Options for file upload operations.
|
|
|
|
```swift
|
|
public struct FileOptions {
|
|
/// The Content-Type header value (auto-inferred if not specified)
|
|
var contentType: String?
|
|
|
|
/// Optional extra headers for the request
|
|
var headers: [String: String]?
|
|
}
|
|
```
|
|
|
|
### BucketOptions
|
|
|
|
Options for bucket creation/update.
|
|
|
|
```swift
|
|
public struct BucketOptions {
|
|
/// Whether the bucket is publicly accessible (default: true)
|
|
var isPublic: Bool
|
|
}
|
|
```
|
|
|
|
### ListOptions
|
|
|
|
Options for listing files.
|
|
|
|
```swift
|
|
public struct ListOptions {
|
|
/// Filter objects by key prefix
|
|
var prefix: String?
|
|
|
|
/// Maximum number of results (1-1000, default: 100)
|
|
var limit: Int
|
|
|
|
/// Offset for pagination (default: 0)
|
|
var offset: Int
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## StoredFile Model
|
|
|
|
The response model for storage operations.
|
|
|
|
```swift
|
|
public struct StoredFile {
|
|
let bucket: String // Bucket name
|
|
let key: String // Object key/path
|
|
let size: Int // File size in bytes
|
|
let mimeType: String? // MIME type
|
|
let uploadedAt: Date // Upload timestamp
|
|
let url: String // Public or signed URL
|
|
}
|
|
```
|