SeaVerse Utils SDK - Utility toolkit including file upload, image compression, and more
npm install @seaverse/utils-sdkSeaVerse Utils SDK - A utility toolkit including file upload, image compression, and more.


- 📤 File Upload - Two-step upload with presigned URLs, secure and efficient
- 🖼️ Image Compression - Auto compress to 1080p, configurable quality and dimensions
- 📊 Upload Progress - Real-time progress callback with speed and remaining time
- ✅ File Validation - Size and type validation
- ⚡ TypeScript - Complete type definitions
- 🌍 Environment Config - Support for multiple environment switching
``bash`
npm install @seaverse/utils-sdkor
pnpm add @seaverse/utils-sdk
`typescript
import { UtilsClient } from '@seaverse/utils-sdk';
// Initialize client
const client = new UtilsClient({
token: 'your-bearer-token',
});
// Upload file
const file = document.querySelector('input[type="file"]').files[0];
const result = await client.uploadFile(file);
console.log('CDN URL:', result.cdnUrl);
console.log('File size:', result.fileSize);
console.log('Compressed:', result.compressed);
`
`typescriptProgress: ${progress.percent}%
const result = await client.uploadFile(file, {
onProgress: (progress) => {
console.log();Stage: ${progress.stage}
console.log();Speed: ${progress.speed} bytes/sec
console.log();Remaining time: ${progress.remainingTime} sec
console.log();`
},
});
`typescript`
const result = await client.uploadFile(file, {
compress: false, // Disable compression
});
`typescript`
const client = new UtilsClient({
token: 'your-bearer-token',
compress: {
enabled: true,
maxWidth: 1920, // Custom max width
maxHeight: 1080, // Custom max height
quality: 0.9, // Custom compression quality
},
});
#### Constructor
`typescript`
new UtilsClient(options: UtilsClientOptions)
Parameters:
- token (string, required): Bearer TokenbaseURL
- (string, optional): API base URL, default https://resource.seaverse.aitimeout
- (number, optional): Request timeout (ms), default 60000compress
- (CompressionConfig, optional): Image compression config
CompressionConfig:
- enabled (boolean): Enable compression, default truemaxWidth
- (number): Max width, default 1080maxHeight
- (number): Max height, default 1080quality
- (number): Compression quality (0-1), default 0.8
#### uploadFile()
Upload file with automatic compression, validation, and upload flow.
`typescript`
async uploadFile(file: File, options?: UploadOptions): Promise
Parameters:
- file: File object to uploadoptions
- (optional):onProgress
- : Progress callback functioncompress
- : Whether to compress (overrides global config)metadata
- : Custom metadata
Returns:
`typescript`
{
fileName: string // File name
originalFileName: string // Original file name
cdnUrl: string // CDN access URL
objectPath: string // Storage path
fileSize: number // File size (bytes)
originalSize: number // Original size (bytes)
compressed: boolean // Whether compressed
contentType: string // MIME type
duration: number // Upload duration (ms)
expiresAt: string // Expiration time
}
Errors:
- Throws UtilsAPIError on failure
Example:
`typescriptUpload failed [${error.code}]: ${error.message}
try {
const result = await client.uploadFile(file, {
onProgress: (progress) => {
updateProgressBar(progress.percent);
},
});
console.log('Upload successful:', result.cdnUrl);
} catch (error) {
if (error instanceof UtilsAPIError) {
console.error();`
}
}
#### setToken()
Update Bearer Token.
`typescript`
setToken(token: string): void
#### setBaseURL()
Update base URL.
`typescript`
setBaseURL(baseURL: string): void
#### updateCompressionConfig()
Update compression config.
`typescript`
updateCompressionConfig(config: Partial
Validate file size and type.
`typescript
import { validateFile } from '@seaverse/utils-sdk';
const result = validateFile(file, {
maxSize: 10 1024 1024, // 10MB
allowedTypes: ['image/jpeg', 'image/png'],
});
if (!result.valid) {
console.error('Validation failed:', result.errors);
}
`
Manually compress image.
`typescript
import { compressImage } from '@seaverse/utils-sdk';
const result = await compressImage(file, {
maxWidth: 1920,
maxHeight: 1080,
quality: 0.8,
});
console.log('Compression ratio:', result.compressionRatio);
console.log('Compressed size:', result.compressedSize);
`
Format bytes to human-readable string.
`typescript
import { formatBytes } from '@seaverse/utils-sdk';
console.log(formatBytes(1024)); // "1 KB"
console.log(formatBytes(1048576)); // "1 MB"
console.log(formatBytes(1073741824)); // "1 GB"
`
`typescript
import { UtilsAPIError, ErrorCode } from '@seaverse/utils-sdk';
try {
const result = await client.uploadFile(file);
} catch (error) {
if (error instanceof UtilsAPIError) {
switch (error.code) {
case ErrorCode.FILE_TOO_LARGE:
alert('File too large, please select a file smaller than 100MB');
break;
case ErrorCode.INVALID_FILE_TYPE:
alert('Unsupported file type');
break;
case ErrorCode.NETWORK_ERROR:
alert('Network error, please check your connection');
break;
default:
alert(Upload failed: ${error.message});`
}
}
}
| Error Code | Description |
|------------|-------------|
| FILE_TOO_LARGE | File size exceeds limit |INVALID_FILE_TYPE
| | Unsupported file type |PRESIGNED_URL_FAILED
| | Failed to get presigned URL |UPLOAD_FAILED
| | Upload failed |COMPRESSION_FAILED
| | Image compression failed |NETWORK_ERROR
| | Network error |TIMEOUT
| | Request timeout |VALIDATION_FAILED
| | File validation failed |
The SDK provides predefined environment URLs:
`typescript
import { UtilsClient, ENVIRONMENT_URLS } from '@seaverse/utils-sdk';
// Production environment (default)
const client = new UtilsClient({
token: prodToken,
// baseURL defaults to 'https://resource.seaverse.ai'
});
// Staging/Test environment
const stagingClient = new UtilsClient({
baseURL: ENVIRONMENT_URLS.STAGING, // 'https://resource.sg.seaverse.dev'
token: stagingToken,
});
// Local development
const localClient = new UtilsClient({
baseURL: ENVIRONMENT_URLS.LOCAL, // 'http://localhost:8003'
token: localToken,
});
`
| Environment | URL | Constant |
|-------------|-----|----------|
| Production | https://resource.seaverse.ai | ENVIRONMENT_URLS.PRODUCTION |https://resource.sg.seaverse.dev
| Staging | | ENVIRONMENT_URLS.STAGING |http://localhost:8003
| Local | | ENVIRONMENT_URLS.LOCAL |
`typescript
import { SeaVerseBackendAPIClient } from '@seaverse/auth-sdk';
import { UtilsClient } from '@seaverse/utils-sdk';
// 1. Login with Auth SDK
const authClient = new SeaVerseBackendAPIClient({
appId: 'your-app-id',
});
const loginResult = await authClient.login({
email: 'user@example.com',
password: 'password',
});
// 2. Initialize Utils SDK with the same token
const utilsClient = new UtilsClient({
token: loginResult.token,
});
// 3. Upload file
const result = await utilsClient.uploadFile(file);
`
The SDK uses presigned URL two-step upload mode:
`
1. Get presigned URL
POST /api/v1/resources/presign-upload
→ Returns upload_url and cdn_url
2. Upload to GCS
PUT {upload_url}
→ Direct upload to Google Cloud Storage
3. Return CDN URL
Use cdn_url to access the file
`
Advantages:
- ✅ Secure: Token not exposed to third-party storage
- ✅ Efficient: Direct upload to GCS, no backend proxy
- ✅ Reliable: GCS provides high availability guarantee
- Max size: 1080×1080 pixels (default config)
- Maintains aspect ratio with auto scaling
- Configurable compression quality (0-1)
- Supports custom max width/height (maxWidth, maxHeight)
Compression only occurs when all conditions are met:
1. File is an image type (MIME type starts with image/)compress.enabled === true
2. Compression is enabled ()options.compress !== false
3. Not explicitly disabled in upload options ()
`typescript
// Method 1: Disable globally
const client = new UtilsClient({
token: 'xxx',
compress: { enabled: false },
});
// Method 2: Disable for single upload
const result = await client.uploadFile(file, {
compress: false,
});
`
A: Get Bearer Token by logging in with @seaverse/auth-sdk
A:
- Images: JPEG, PNG, GIF, WebP
- Documents: PDF, TXT, MD
- Others: Depends on backend configuration
A:
- Default limit: 100MB
- Can be customized via validation rules
- Images are auto-compressed to reduce transfer size
A:
`typescript`
try {
await client.uploadFile(file);
} catch (error) {
if (error instanceof UtilsAPIError) {
// Handle based on error code
if (error.code === ErrorCode.NETWORK_ERROR) {
// Retry logic
}
}
}
A:
- Default quality is 0.8, balancing file size and image quality
- Adjustable via quality parameter (0-1)
- Recommended range: 0.7-0.9
`bashInstall dependencies
pnpm install
MIT © SeaVerse Team
- 🎉 Initial release
- ✨ Support file upload (presigned URL mode)
- ✨ Support auto image compression (1080p)
- ✨ Support upload progress callback
- ✨ Support file validation
- ✨ Complete TypeScript type definitions