cloud-storage-web

# Cloud Storage Web SDK

Use this skill when building web applications that need to upload, download, or manage files using CloudBase cloud storage via the `@cloudbase/js-sdk` (Web SDK).

## When to use this skill

Use this skill for **file storage operations** in web applications when you need to:

- Upload files from web browsers to CloudBase cloud storage
- Generate temporary download URLs for stored files
- Delete files from cloud storage
- Download files from cloud storage to local browser

**Do NOT use for:**
- Mini-program file operations (use mini-program specific skills)
- Backend file operations (use Node SDK skills)
- Database operations (use database skills)

## How to use this skill (for a coding agent)

1. **Initialize CloudBase SDK**
   - Ask the user for their CloudBase environment ID
   - Always use the standard initialization pattern shown below

2. **Choose the right storage method**
   - `uploadFile` - For uploading files from browser to cloud storage
   - `getTempFileURL` - For generating temporary download links
   - `deleteFile` - For deleting files from storage
   - `downloadFile` - For downloading files to browser

3. **Handle CORS requirements**
   - Remind users to add their domain to CloudBase console security domains
   - This prevents CORS errors during file operations

4. **Follow file path rules**
   - Use valid characters: `[0-9a-zA-Z]`, `/`, `!`, `-`, `_`, `.`, ` `, `*`, Chinese characters
   - Use `/` for folder structure (e.g., `folder/file.jpg`)

---

## SDK Initialization

```javascript
import cloudbase from "@cloudbase/js-sdk";

const app = cloudbase.init({
  env: "your-env-id", // Replace with your CloudBase environment ID
});
```

**Initialization rules:**
- Always use synchronous initialization with the pattern above
- Do not lazy-load the SDK with dynamic imports
- Keep a single shared `app` instance across your application

## File Upload (uploadFile)

### Basic Usage

```javascript
const result = await app.uploadFile({
  cloudPath: "folder/filename.jpg", // File path in cloud storage
  filePath: fileInput.files[0],     // HTML file input element
});

// Result contains:
{
  fileID: "cloud://env-id/folder/filename.jpg", // Unique file identifier
  // ... other metadata
}
```

### Advanced Upload with Progress

```javascript
const result = await app.uploadFile({
  cloudPath: "uploads/avatar.jpg",
  filePath: selectedFile,
  method: "put", // "post" or "put" (default: "put")
  onUploadProgress: (progressEvent) => {
    const percent = Math.round(
      (progressEvent.loaded * 100) / progressEvent.total
    );
    console.log(`Upload progress: ${percent}%`);
    // Update UI progress bar here
  }
});
```

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cloudPath` | string | Yes | Absolute path with filename (e.g., "folder/file.jpg") |
| `filePath` | File | Yes | HTML file input object |
| `method` | "post" \| "put" | No | Upload method (default: "put") |
| `onUploadProgress` | function | No | Progress callback function |

### Cloud Path Rules

- **Valid characters**: `[0-9a-zA-Z]`, `/`, `!`, `-`, `_`, `.`, ` `, `*`, Chinese characters
- **Invalid characters**: Other special characters
- **Structure**: Use `/` to create folder hierarchy
- **Examples**:
  - `"avatar.jpg"`
  - `"uploads/avatar.jpg"`
  - `"user/123/avatar.jpg"`

### CORS Configuration

**⚠️ IMPORTANT:** To prevent CORS errors, add your domain to CloudBase console:

1. Go to CloudBase Console → Environment → Security Sources → Security Domains
2. Add your frontend domain (e.g., `https://your-app.com`, `http://localhost:3000`)
3. If CORS errors occur, remove and re-add the domain

## Temporary Download URLs (getTempFileURL)

### Basic Usage

```javascript
const result = await app.getTempFileURL({
  fileList: [
    {
      fileID: "cloud://env-id/folder/filename.jpg",
      maxAge: 3600 // URL valid for 1 hour (seconds)
    }
  ]
});

// Access the download URL
result.fileList.forEach(file => {
  if (file.code === "SUCCESS") {
    console.log("Download URL:", file.tempFileURL);
    // Use this URL to download or display the file
  }
});
```

### Multiple Files

```javascript
const result = await app.getTempFileURL({
  fileList: [
    {
      fileID: "cloud://env-id/image1.jpg",
      maxAge: 7200 // 2 hours
    },
    {
      fileID: "cloud://env-id/document.pdf",
      maxAge: 86400 // 24 hours
    }
  ]
});
```

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `fileList` | Array | Yes | Array of file objects |

#### fileList Item Structure

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `fileID` | string | Yes | Cloud storage file ID |
| `maxAge` | number | Yes | URL validity period in seconds |

### Response Structure

```javascript
{
  code: "SUCCESS",
  fileList: [
    {
      code: "SUCCESS",
      fileID: "cloud://env-id/folder/filename.jpg",
      tempFileURL: "https://temporary-download-url"
    }
  ]
}
```

### Best Practices

- Set appropriate `maxAge` based on use case (1 hour to 24 hours)
- Handle `SUCCESS`/`ERROR` codes in response
- Use temporary URLs for private file access
- Cache URLs if needed, but respect expiration time

## File Deletion (deleteFile)

### Basic Usage

```javascript
const result = await app.deleteFile({
  fileList: [
    "cloud://env-id/folder/filename.jpg"
  ]
});

// Check deletion results
result.fileList.forEach(file => {
  if (file.code === "SUCCESS") {
    console.log("File deleted:", file.fileID);
  } else {
    console.error("Failed to delete:", file.fileID);
  }
});
```

### Multiple Files

```javascript
const result = await app.deleteFile({
  fileList: [
    "cloud://env-id/old-avatar.jpg",
    "cloud://env-id/temp-upload.jpg",
    "cloud://env-id/cache-file.dat"
  ]
});
```

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `fileList` | Array<string> | Yes | Array of file IDs to delete |

### Response Structure

```javascript
{
  fileList: [
    {
      code: "SUCCESS",
      fileID: "cloud://env-id/folder/filename.jpg"
    }
  ]
}
```

### Best Practices

- Always check response codes before assuming deletion success
- Use this for cleanup operations (old avatars, temp files, etc.)
- Consider batching multiple deletions for efficiency

## File Download (downloadFile)

### Basic Usage

```javascript
const result = await app.downloadFile({
  fileID: "cloud://env-id/folder/filename.jpg"
});

// File is downloaded to browser default download location
```

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `fileID` | string | Yes | Cloud storage file ID |

### Response Structure

```javascript
{
  // Success response (no specific data returned)
  // File is downloaded to browser
}
```

### Best Practices

- Use for user-initiated downloads (save file dialogs)
- For programmatic file access, use `getTempFileURL` instead
- Handle download errors appropriately

## Error Handling

All storage operations should include proper error handling:

```javascript
try {
  const result = await app.uploadFile({
    cloudPath: "uploads/file.jpg",
    filePath: selectedFile
  });

  if (result.code) {
    // Handle error
    console.error("Upload failed:", result.message);
  } else {
    // Success
    console.log("File uploaded:", result.fileID);
  }
} catch (error) {
  console.error("Storage operation failed:", error);
}
```

### Common Error Codes

- `INVALID_PARAM` - Invalid parameters
- `PERMISSION_DENIED` - Insufficient permissions
- `RESOURCE_NOT_FOUND` - File not found
- `SYS_ERR` - System error


## Best Practices

1. **File Organization**: Use consistent folder structures (`uploads/`, `avatars/`, `documents/`)
2. **Naming Conventions**: Use descriptive filenames with timestamps if needed
3. **Progress Feedback**: Show upload progress for better UX
4. **Cleanup**: Delete temporary/unused files to save storage costs
5. **Security**: Validate file types and sizes before upload
6. **Caching**: Cache download URLs appropriately but respect expiration
7. **Batch Operations**: Use arrays for multiple file operations when possible

## Performance Considerations

1. **File Size Limits**: Be aware of CloudBase file size limits
2. **Concurrent Uploads**: Limit concurrent uploads to prevent browser overload
3. **Progress Monitoring**: Use progress callbacks for large file uploads
4. **Temporary URLs**: Generate URLs only when needed, with appropriate expiration

## Security Considerations

1. **Domain Whitelisting**: Always configure security domains to prevent CORS issues
2. **Access Control**: Use appropriate file permissions (public vs private)
3. **URL Expiration**: Set reasonable expiration times for temporary URLs
4. **User Permissions**: Ensure users can only access their own files when appropriate