Classic Cloud Storage

In classic mode, the CloudBase Flutter SDK operates the environment's built-in cloud storage through app.storage.from(). Upload APIs take a relative path and return a full fileID. Download, delete, and signed URL APIs take the full fileID.

Differences from PG mode

Key API differences between classic mode and PG mode:

Dimension	Classic mode	PG mode
Entry	`app.storage.from()`	`app.storage.fromBucket(bucketId)`
Path	Relative path for upload, copy, and move; `cloud://` fileID for download, delete, and signed URLs	Object name inside the bucket, such as `user-123/avatar.png`
Permissions	Built-in permissions plus JSON security rules	PostgreSQL RLS (Row Level Security)
Overwrite default	`upsert` defaults to `true`	`upsert` defaults to `false`
Bucket management	Not supported	`createBucket` / `listBuckets` and related methods
File listing	Not supported	`list()`
Public URL	Not supported	`getPublicUrl()` builds the URL locally
Object info	Not supported	`info()` / `exists()`

See PG mode Cloud Storage.

Initialization

final app = await CloudBase.init(
  env: 'your-env-id',
  accessKey: 'your-access-key',
);

final storage = app.storage.from();

upload

Future<StorageResponse<StorageUploadResult>> storage.upload(
  String path,
  List<int> fileData, {
  StorageUploadOptions? options,
})

Upload file to cloud storage. This method will first get upload info, then upload file to COS, and finally return fileID.

Parameters

path

String

Cloud storage relative path, e.g. `images/photo.jpg`.

fileData

List<int>

File byte data.

options

StorageUploadOptions

Upload options.

Response

data

Object

Return data

error

StorageError?

Error message.

Example

Upload File
Upload Options

final app = await CloudBase.init(
  env: 'your-env-id',
  accessKey: 'your-access-key',
);

final storage = app.storage.from();

// Pick image and upload
Future<void> uploadImage() async {
  final picker = ImagePicker();
  final XFile? image = await picker.pickImage(source: ImageSource.gallery);

  if (image == null) return;

  final fileBytes = await image.readAsBytes();

  final result = await storage.upload(
    'images/${image.name}',
    fileBytes,
    options: StorageUploadOptions(
      contentType: 'image/jpeg',
      cacheControl: 'max-age=3600',
    ),
  );

  if (result.isSuccess) {
    print('Upload successful: ${result.data?.id}');
    print('File path: ${result.data?.path}');
  } else {
    print('Upload failed: ${result.error?.message}');
  }
}

// Do not overwrite existing file
final result = await storage.upload(
  'images/photo.jpg',
  fileBytes,
  options: StorageUploadOptions(upsert: false),
);

// Custom metadata
final result = await storage.upload(
  'images/photo.jpg',
  fileBytes,
  options: StorageUploadOptions(
    metadata: {'userId': '123', 'category': 'avatar'},
  ),
);

getUploadInfo

Future<StorageResponse<List<StorageUploadInfo>>> storage.getUploadInfo(
  List<String> paths,
)

Get file upload info. Returns upload URL and other info for client to directly upload files to COS.

Parameters

paths

List<String>

File path list (cloud storage relative path).

Response

data

List<StorageUploadInfo>?

Upload info list.

error

StorageError?

Error message.

Example

Get Upload Info

final result = await storage.getUploadInfo([
  'images/photo.jpg',
  'documents/report.pdf',
]);

if (result.isSuccess) {
  for (final info in result.data!) {
    print('Path: ${info.path}');
    print('Upload URL: ${info.uploadUrl}');
    print('File ID: ${info.fileId}');
  }
}

getDownloadUrls

Future<StorageResponse<List<StorageDownloadInfo>>> storage.getDownloadUrls(
  List<String> fileIds, {
  int? expiresIn,
})

Get file download URLs.

Parameters

fileIds

List<String>

File ID list (full cloudObjectId, e.g. `cloud://envId.xxx/path/file.jpg`).

expiresIn

int?

Temporary link lifetime in seconds. Sent to the gateway as `maxAge`.

Response

data

List<StorageDownloadInfo>?

Download info list.

error

StorageError?

Error message.

Example

Get Download URLs

final result = await storage.getDownloadUrls([
  'cloud://envId.xxx/images/photo.jpg',
  'cloud://envId.xxx/documents/report.pdf',
]);

if (result.isSuccess) {
  for (final info in result.data!) {
    if (info.isSuccess) {
      print('Download URL: ${info.downloadUrl}');
    } else {
      print('Failed to get: ${info.message}');
    }
  }
}

createSignedUrl

Future<StorageResponse<String>> storage.createSignedUrl(
  String fileId,
  int expiresIn,
)

Create signed URL (temporary access link).

Parameters

fileId

String

Full fileID.

expiresIn

int

Expiration time (seconds).

Response

data

String?

Signed URL.

error

StorageError?

Error message.

Example

Create Signed URL

final result = await storage.createSignedUrl(
  'cloud://envId.xxx/images/photo.jpg',
  3600, // 1 hour expiration
);

if (result.isSuccess) {
  print('Signed URL: ${result.data}');
}

createSignedUrls

Future<StorageResponse<List<StorageDownloadInfo>>> storage.createSignedUrls(
  List<String> fileIds,
  int expiresIn,
)

Batch create signed URLs.

Parameters

fileIds

List<String>

Full fileID list.

expiresIn

int

Expiration time (seconds).

Response

data

List<StorageDownloadInfo>?

Download info list.

error

StorageError?

Error message.

Example

Batch Create Signed URLs

final result = await storage.createSignedUrls(
  [
    'cloud://envId.xxx/images/photo1.jpg',
    'cloud://envId.xxx/images/photo2.jpg',
  ],
  3600,
);

if (result.isSuccess) {
  for (final info in result.data!) {
    print('${info.fileId}: ${info.downloadUrl}');
  }
}

remove

Future<StorageResponse<List<StorageDeleteResult>>> storage.remove(
  List<String> fileIds,
)

Delete files.

Parameters

fileIds

List<String>

File ID list to delete (full fileID).

Response

data

List<StorageDeleteResult>?

Delete result list.

error

StorageError?

Error message.

Example

Delete Files

final result = await storage.remove([
  'cloud://envId.xxx/images/photo.jpg',
  'cloud://envId.xxx/documents/report.pdf',
]);

if (result.isSuccess) {
  for (final item in result.data!) {
    if (item.isSuccess) {
      print('Delete successful: ${item.fileId}');
    } else {
      print('Delete failed: ${item.fileId} - ${item.message}');
    }
  }
}

copy

Future<StorageResponse<StorageCopyResult>> storage.copy(
  String fromPath,
  String toPath, {
  bool overwrite = true,
})

Copy file.

Parameters

fromPath

String

Source file path (relative path).

toPath

String

Target file path (relative path).

overwrite

bool

Whether to overwrite if target exists, default `true`.

Response

data

StorageCopyResult?

Copy result.

error

StorageError?

Error message.

Example

Copy File

final result = await storage.copy(
  'images/photo.jpg',
  'images/backup/photo.jpg',
);

if (result.isSuccess) {
  print('Copy successful: ${result.data?.cloudObjectId}');
} else {
  print('Copy failed: ${result.error?.message}');
}

copyBatch

Future<StorageResponse<List<StorageCopyResult>>> storage.copyBatch(
  List<Map<String, dynamic>> items,
)

Batch copy files.

Parameters

items

List<Map<String, dynamic>>

Copy items. Each item has `srcPath` and `dstPath`. `from` and `to` are accepted as aliases. Optional `overwrite` (replace an existing target, default true) and `removeOriginal` (delete the source after copying, default false).

Response

data

List<StorageCopyResult>?

Copy result list.

error

StorageError?

Error message.

Example

Batch Copy Files

final result = await storage.copyBatch([
  {'srcPath': 'images/photo1.jpg', 'dstPath': 'backup/photo1.jpg'},
  {'srcPath': 'images/photo2.jpg', 'dstPath': 'backup/photo2.jpg'},
]);

if (result.isSuccess) {
  for (final item in result.data!) {
    if (item.isSuccess) {
      print('Copy successful: ${item.cloudObjectId}');
    }
  }
}

move

Future<StorageResponse<StorageCopyResult>> storage.move(
  String fromPath,
  String toPath, {
  bool overwrite = true,
})

Move file (implemented by copy + removeOriginal).

Parameters

fromPath

String

Source file path (relative path).

toPath

String

Target file path (relative path).

overwrite

bool

Whether to overwrite if target exists, default `true`.

Response

data

StorageCopyResult?

Move result.

error

StorageError?

Error message.

Example

Move File

final result = await storage.move(
  'images/old.jpg',
  'images/new.jpg',
);

if (result.isSuccess) {
  print('Move successful: ${result.data?.cloudObjectId}');
} else {
  print('Move failed: ${result.error?.message}');
}

StorageUploadOptions

Upload options:

Parameter	Type	Description
`cacheControl`	`String?`	Cache control, e.g. `max-age=3600`
`contentType`	`String?`	File MIME type, e.g. `image/jpeg`
`metadata`	`Map<String, dynamic>?`	Custom metadata
`upsert`	`bool`	Whether to overwrite existing file, default `true`

StorageUploadResult

Upload result:

Parameter	Type	Description
`id`	`String?`	CloudBase fileID
`path`	`String?`	Upload path
`fullPath`	`String?`	File full path

StorageUploadInfo

Upload info:

Parameter	Type	Description
`path`	`String?`	File path
`uploadUrl`	`String?`	Upload URL
`token`	`String?`	Upload token
`authorization`	`String?`	Upload authorization
`fileId`	`String?`	File ID
`cosFileId`	`String?`	COS file ID
`code`	`String?`	Error code
`message`	`String?`	Error message

StorageDownloadInfo

Download info:

Parameter	Type	Description
`fileId`	`String?`	File ID
`downloadUrl`	`String?`	Download URL
`code`	`String?`	Error code (on partial failure)
`message`	`String?`	Error message (on partial failure)

StorageDeleteResult

Delete result:

Parameter	Type	Description
`fileId`	`String?`	File ID
`code`	`String?`	Error code (on partial failure)
`message`	`String?`	Error message (on partial failure)

StorageCopyResult

Copy result:

Parameter	Type	Description
`cloudObjectId`	`String?`	Cloud file ID of copied object
`code`	`String?`	Error code (on partial failure)
`message`	`String?`	Error message (on partial failure)

StorageResponse<T>

Storage response:

Parameter	Type	Description
`data`	`T?`	Response data
`error`	`StorageError?`	Error message

StorageError

Storage error:

Parameter	Type	Description
`code`	`String?`	Error code
`message`	`String?`	Error message
`requestId`	`String?`	Request ID

Initialization​

upload​

Parameters

Response

Example

getUploadInfo​

Parameters

Response

Example

getDownloadUrls​

Parameters

Response

Example

createSignedUrl​

Parameters

Response

Example

createSignedUrls​

Parameters

Response

Example

remove​

Parameters

Response

Example

copy​

Parameters

Response

Example

copyBatch​

Parameters

Response

Example

move​

Parameters

Response

Example

Storage Related Types​

StorageUploadOptions​

StorageUploadResult​

StorageUploadInfo​

StorageDownloadInfo​

StorageDeleteResult​

StorageCopyResult​

StorageResponse<T>​

StorageError​

Initialization

upload

getUploadInfo

getDownloadUrls

createSignedUrl

createSignedUrls

remove

copy

copyBatch

move

Storage Related Types

StorageUploadOptions

StorageUploadResult

StorageUploadInfo

StorageDownloadInfo

StorageDeleteResult

StorageCopyResult

StorageResponse<T>

StorageError