Download & Delete

Get public or time-limited URLs for files, download file bytes directly, and permanently remove files from storage.

Get a download URL

Returns a URL that can be used to access the file. Use this in Image.network(), opened in a browser, or passed to a video player.

lib/storage.dartDart

final url = await Koolbase.storage.getDownloadUrl(
  bucket: 'avatars',
  path: 'user_${userId}.jpg',
);

// Use in a Flutter widget
Image.network(url)

Public URL from R2

The download URL is the public Cloudflare R2 URL for the file. It remains valid as long as the file exists and your R2 bucket is configured for public access. There is no expiry on download URLs in the current implementation.

Download file bytes

Download the raw bytes of a file directly into your app:

lib/storage.dartDart

final bytes = await Koolbase.storage.downloadBytes(
  bucket: 'documents',
  path: 'reports/q3-report.pdf',
);

// Save to local file
final localFile = File('${tempDir}/q3-report.pdf');
await localFile.writeAsBytes(bytes);

// Or display directly
// e.g. open with a PDF viewer package

List files in a bucket

List all files in a bucket, optionally filtered by path prefix:

lib/storage.dartDart

// List all files in a bucket
final files = await Koolbase.storage.list(bucket: 'avatars');

// List files with a path prefix
final userFiles = await Koolbase.storage.list(
  bucket: 'attachments',
  prefix: 'posts/${postId}/',
);

for (final file in files) {
  print(file.path);        // user_abc123.jpg
  print(file.size);        // size in bytes
  print(file.contentType); // image/jpeg
  print(file.createdAt);   // DateTime
}

Delete a file

Permanently removes a file from R2 and its metadata from the database. This cannot be undone.

lib/storage.dartDart

await Koolbase.storage.delete(
  bucket: 'avatars',
  path: 'user_${userId}.jpg',
);

Deletion is permanent

Deleted files cannot be recovered. If your app allows users to delete files, consider keeping the metadata record and marking it as deleted rather than calling this endpoint directly — or confirm with the user before deleting.

Common pattern — profile avatar

A complete example for uploading and displaying a user avatar:

lib/profile_screen.dartDart

Future<void> updateAvatar(Uint8List imageBytes, String userId) async {
  // Upload new avatar (overwrites existing)
  await Koolbase.storage.uploadBytes(
    imageBytes,
    bucket: 'avatars',
    path: 'user_$userId.jpg',
    contentType: 'image/jpeg',
  );

  // Get the URL and update the user's profile record
  final url = await Koolbase.storage.getDownloadUrl(
    bucket: 'avatars',
    path: 'user_$userId.jpg',
  );

  await Koolbase.db
    .collection('profiles')
    .doc(userId)
    .update({'avatar_url': url});
}